This patch adds the following content type definitions, to be used by
endpoint authors implementing MARC-related endpoints:
--------------------------------------
| Content-type | Alias |
|--------------------------|---------|
| application/marcxml+xml | marcxml |
| application/marc-in-json | mij |
| application/marc | marc |
--------------------------------------
Code using this aliases will use them like this:
- Suppose you want to output data in MARCXML format:
my $record = cool_method_that_returns_MARC_RECORD();
return $c->render( status => 200, format => 'marcxml', text => $record->as_xml_record );
Note: 'text' by defaults encodes output as UTF-8. If the encoding is not
UTF-8 you should encode the data on your own.
To test:
- Apply this patches
- Run:
$ kshell
k$ prove t/db_dependent/Koha/REST/V1.t
=> SUCCESS: Test pass!
- Sign off :-D
Signed-off-by: Michal Denar <black23@gmail.com>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
This patch adds plugins the capability of injecting new routes on the
API.
The plugins should provide the following methods to be considered valid API-generating plugins:
- 'api_routes': returning the 'path' component of the OpenAPI specification corresponding to the routes served by the plugin
- 'api_namespace': it should return a namespace to be used for grouping the endpoints provided by the plugin
otherwise, they will be just skipped.
All plugin-generated routes will be added the 'contrib' namespace, and
will end up placed inside /contrib/<namespace>, where <namespace> is what the 'api_namespace' returns.
A sample endpoint will be added to the Kitchen Sink plugin, and tests
are being written.
To test:
- Apply this patches
- Run:
$ kshell
k$ prove t/db_dependent/Koha/REST/Plugin/PluginRoutes.t
=> SUCCESS: Tests pass!
- Install the (latest) KitchenSink plugin
- Point your browser to the API like this:
http://koha-intra.myDNSname.org:8081/api/v1/.html
=> SUCCESS: The /contrib/kitchensink/patrons/:patron_id/bother endpoint
implemented by the plugin has been merged!
- Sign off! :-D
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@deichman.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Alex Arnaud <alex.arnaud@biblibre.com>
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
It implements only the "client credentials" flow with no scopes
support. API clients are tied to an existing patron and have the same
permissions as the patron they are tied to.
API Clients are defined in $KOHA_CONF.
Test plan:
0. Install Net::OAuth2::AuthorizationServer 0.16
1. In $KOHA_CONF, add an <api_client> element under <config>:
<api_client>
<client_id>$CLIENT_ID</client_id>
<client_secret>$CLIENT_SECRET</client_secret>
<patron_id>X</patron_id> <!-- X is an existing borrowernumber -->
</api_client>
2. Apply patch, run updatedatabase.pl and reload starman
3. Install Firefox extension RESTer [1]
4. In RESTer, go to "Authorization" tab and create a new OAuth2
configuration:
- OAuth flow: Client credentials
- Access Token Request Method: POST
- Access Token Request Endpoint: http://$KOHA_URL/api/v1/oauth/token
- Access Token Request Client Authentication: Credentials in request
body
- Client ID: $CLIENT_ID
- Client Secret: $CLIENT_SECRET
5. Click on the newly created configuration to generate a new token
(which will be valid only for an hour)
6. In RESTer, set HTTP method to GET and url to
http://$KOHA_URL/api/v1/patrons then click on SEND
If patron X has permission 'borrowers', it should return 200 OK
with the list of patrons
Otherwise it should return 403 with the list of required permissions
(Please test both cases)
7. Wait an hour (or run the following SQL query:
UPDATE oauth_access_tokens SET expires = 0) and repeat step 6.
You should have a 403 Forbidden status, and the token must have been
removed from the database.
8. Create a bunch of tokens using RESTer, make some of them expires
using the previous SQL query, and run the following command:
misc/cronjobs/cleanup_database.pl --oauth-tokens
Verify that expired tokens were removed, and that the others are
still there
9. prove t/db_dependent/api/v1/oauth.t
[1] https://addons.mozilla.org/en-US/firefox/addon/rester/
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch removes the /api/v1/app.pl prefix from generated baseUrl.
It has the consequence of hardcoding / as the base path for the API.
This is ok because we don't currently support mounting Koha pieces in
different than hardcoded paths (/cgi-bin/koha?), but certainly worth
mentioning because this will need to depend on a syspref or config entry
when someone chages this behviour.
To test:
- On master, point your browser to:
http://kohadev.mydnsname.org:8080/api/v1/
=> FAIL: basePath looks like /api/v1/app.pl/api/v1
- Apply this patch
- Restart memcached and plack:
$ restart_all
or
$ sudo systemctl restart memcached && sudo systemctl restart
koha-common
- Reload http://kohadev.mydnsname.org:8080/api/v1/
=> SUCCESS: basePath is /api/v1
- Sign off :-D
Signed-off-by: Julian Maurice <julian.maurice@biblibre.com>
Signed-off-by: Katrin Fischer <katrin.fischer.83@web.de>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Julian Maurice <julian.maurice@biblibre.com>
Signed-off-by: Lari Taskula <lari.taskula@jns.fi>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Lari Taskula <lari.taskula@jns.fi>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch just initializes the plugin on the main controller class so
it is available for all endpoints to use.
As it is not used, in order to test just restart plack and make sure the
endpoints work (run the t/db_dependent/api/v1 tests).
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Lari Taskula <lari.taskula@jns.fi>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
This patch migrates from Swagger2 to Mojolicious::Plugin::OpenAPI as Swagger2 is
no longer actively maintained.
This migration involves some minor changes to our Swagger specification documents
and to controllers. Each operation is migrated in following patches separately.
Please see Mojolicious::Plugin::OpenAPI and its tutorial for more documentation.
The patch also refactors some API authentication -related code by taking advantage
of Koha::Exceptions. Authentication is now handled via Mojolicious's "under->to"
functionality. The actual authentication & authorization checks are moved to
Koha::REST::V1::Auth. Added a HTTP 503 response for when database update is
required, instead of returning an authentication failure as before.
To test:
1. prove t/db_dependent/api/v1/auth.t
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Koha::Issues and Koha::Checkouts have been added to the codebase to
represent the same thing.
In ODLIS the word Issue is never used in the sense we use it. Another
problem with Issue is it has so many meaning in English (such as
problem/bug)
The word Checkout *is* in ODLIS, closer to what we use:
http://www.abc-clio.com/ODLIS/odlis_c.aspx#checkoutslip
Test plan:
git grep Koha::Issue
should not return any occurrences and the tests must still pass
Signed-off-by: Nick Clemens <nick@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
If the user is not authorised to call this route, we would prefer to
raise a 403 instead of 400
Note that we wanted to submit tests for this change but the city code
does not let use do that (we are allowed to list/show cities even
without any permissions). The patrons.t is not complete enought and the
holds.t tests do not pass...
Tomas plans to submit tests but we reach the end of the hackfest ;)
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The idea is to make the code more readable moving the code to its own
subroutine
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch adds to the x-mojo-around action code to give a meaningful
error given a bad query parameter in the query string for a request.
Test Plan
1) Submit an api request to an existing restful endpoint with no query
parameters
2) Confirm the correct response is being given
3) Submit an api request to an existing restful endpoint with an allowed
query parameter
4) Confimr the correct response is being given
5) Submit an api request to an existing restful endpoint with a
malformed query paramter
6) Note the 400 response code and helpful json api body
https://bugs.koha-community.org/show_bug.cgi?id=17445
Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The swagger specification file is currently being minified adding
manual steps to release management and restful api route development.
The minification is not required; The deferenced version of the
specification is now internally validated at runtime and relavant errors
output and the dereferenced schema has been made publically available at
/api/v1/spec, so it can be copy&pasted into validation tools
Test Plan
1) Apply patch
2) Ensure api routes still function (applying the /cities patch might be
helpful)
3) Ensure /api/v1/spec page exists (it should be the de-referenced
swagger.json file)
Signed-off-by: Claire Gravely <claire_gravely@hotmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Brendan Gallagher <brendan@bywatersolutions.com>
To make the QA scripts happy, the POD needed a fix, and also
keys applied to a hashref needs to be avoided.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch changes the permission check order because haspermission
is the smaller check, and going through the patron/user and its guaranteed
before checking if it is (say) a staff member or even a superlibrarian doesn't
seem right.
Bonus: Remove unneeded C4::Auth import in Patron.pm
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
When user does not have required permissions to use API operation, it would be
useful to let them know which permissions he is missing. Since they are now
defined in Swagger, we can easily render them into the response.
To test:
1. Use a patron without any permissions
2. Make GET request to http://yourlib/api/v1/patrons
3. Observe permission error and see that required_permissions are displayed.
4. Run t/db_dependent/api/v1/patrons.t
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Allow access to user's own objects even if they do not have required permissions.
This will be very useful in many cases where an user wants to request their own
object, for example renewing their checkouts or placing a hold for themselves.
First, this patch renames "x-koha-permission" to "x-koha-authorization" in order
to describe the new functionality better.
Second, we can now add two extra parameters under "x-koha-authorization":
- "allow-owner"; Allows the owner of object to access it (without permission)
- "allow-guarantor"; Allows guarantor of the owner of object to access it
(without permission)
Third, since permission checking is outside of actual controller, we need a way
to find out ownership from different types of parameters, e.g. checkout_id from
/checkouts/{checkout_id}, borrowernumber from /patrons/{borrowernumber} etc.
A solution is to match the parameter with a subroutine that is designed to verify
the ownership for that object. See the new subroutines in Koha::REST::V1.
To use this functionality you will simply define it in Swagger:
"/patrons/{borrowernumber}": {
"get": {
...,
"x-koha-authorization": {
"allow-owner": true,
"permissions": {
"borrowers": "1"
}
}
}
}
If a parameter that is not yet defined in Koha::REST::V1::check_object_ownership,
you also need to define it and implement a subroutine that determines ownership.
Tests are provided in a following patch that adds this functionality for current
API operations.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Define 'x-koha-permission' for the Swagger2 Operation Object, to automatically
authorize against the required permissions.
This way we immediately tell the API consumer in the Swagger2-definition, which
permissions are needed to access defined resources.
Also we don't need to maintain permissions in multiple locations and we can build
a smart testing framework to help a lot in creating tests for the new REST API.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
This patch separates Swagger-specifications and the minifySwagger.pl from other
api-files by moving specifications & minifier into api/v1/swagger.
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
We participated in the development of the Mojolicious::Plugin::Swagger and know
it well. We have made an extension to the plugin to provide full CORS support
and have been building all our in-house features on the new REST API.
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Our current approach with splitting the Swagger specification brings problems.
For example, in swagger.json, if we split the whole "definitions" object with
$ref, validations will fail with online.swagger.io validator.
(See http://online.swagger.io/validator/debug?url=url_to_your_swagger_json)
The problem also occurs with "paths" (Paths Object), because simply $ref to all
paths for example in /paths/index.json does not meet the Swagger2 specification.
The problem is solved by using the minification script and the minified version
of swagger.json after which the swagger.min.json is valid Swagger2 specification,
because the minifier resolves the problematic $refs of swagger.json file in the
minified version.
Signed-off-by: Olli-Antti Kivilahti <olli-antti.kivilahti@jns.fi>
My name is Olli-Antti Kivilahti and I approve this commit.
We have been using the Swagger2.0-driven REST API on Mojolicious for 1 year now
in production and I am certain we have a pretty good idea on how to work with
the limitations of Swagger2.0
Signed-off-by: Johanna Raisa <johanna.raisa@gmail.com>
My name is Johanna Räisä and I approve this commit.
We have been using Swagger2.0-driven REST API in production successfully.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
While the original patch fixes the issue, reading at Mojolicious source code, revealed
that Mojo::Transaction already has proper processing for detecting the remote address:
sub remote_address {
my $self = shift;
return $self->original_remote_address(@_) if @_;
return $self->original_remote_address unless $self->req->reverse_proxy;
# Reverse proxy
return ($self->req->headers->header('X-Forwarded-For') // '') =~ /([^,\s]+)$/
? $1
: $self->original_remote_address;
}
Without this patch, if there's a request without HTTP_X_FORWARDED_FOR, then the remote
address would be empty. Such would be the case of a dev/standard setup without Plack.
This patch makes Koha::REST::V1::startup use tx->remote_address instead of dealing with the
headers on its own.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Mojolicious does not set $ENV{REMOTE_ADDR} (neither $ENV{HTTP_*}) as
it may share ENV between different requests.
Fortunately for us, Plack does not!
This is a dirty patch to fix this issue but it seems that there is not
lot of solutions. It adds a remote_addr parameter to
C4::Auth::check_cookie_authin order to send it from
Koha::Rest::V1::startup reading the headers sent by Mojolicious.
Test plan:
Hit /cgi-bin/koha/mainpage.pl
Hit /api/v1/patrons/42
Hit /cgi-bin/koha/mainpage.pl
With this patch applied, everything will be fine and you won't be
logged out.
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
The 'borrower' should not be used anymore, especially for new code.
This patch move files and rename variables newly pushed (i.e. in the Koha
namespace).
Test plan:
1/
git grep Koha::Borrower
should not return code in use.
2/
Prove the different modified test files
3/ Do some clicks in the member^Wpatron module to be sure there is not
an obvious error.
Signed-off-by: Hector Castro <hector.hecaxmmx@gmail.com>
Works as described. Tested with Circulation, Members/Patrons, Discharge,
Restrictions modules and the must common functionalities
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Jesse Weaver <jweaver@bywatersolutions.com>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Joonas Kylmälä <j.kylmala@gmail.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Actual routes are:
/borrowers
Return a list of all borrowers in Koha
/borrowers/{borrowernumber}
Return the borrower identified by {borrowernumber}
(eg. /borrowers/1)
There is a test file you can run with:
$ prove t/db_dependent/rest/borrowers.t
All API stuff is in /api/v1 (except Perl modules)
So we have:
/api/v1/script.cgi CGI script
/api/v1/swagger.json Swagger specification
Change both OPAC and Intranet VirtualHosts to access the API,
so we have:
http://OPAC/api/v1/swagger.json Swagger specification
http://OPAC/api/v1/{path} API endpoint
http://INTRANET/api/v1/swagger.json Swagger specification
http://INTRANET/api/v1/{path} API endpoint
Add a (disabled) virtual host in Apache configuration api.HOSTNAME,
so we have:
http://api.HOSTNAME/api/v1/swagger.json Swagger specification
http://api.HOSTNAME/api/v1/{path} API endpoint
Add 'unblessed' subroutines to both Koha::Objects and Koha::Object to be
able to pass it to Mojolicious
Test plan:
1/ Install Perl modules Mojolicious and Swagger2
2/ perl Makefile.PL
3/ make && make install
4/ Change etc/koha-httpd.conf and copy it to the right place if needed
5/ Reload Apache
6/ Check that http://(OPAC|INTRANET)/api/v1/borrowers and
http://(OPAC|INTRANET)/api/v1/borrowers/{borrowernumber} works
Optionally, you could verify that http://(OPAC|INTRANET)/vX/borrowers
(where X is an integer greater than 1) returns a 404 error
Signed-off-by: Alex Arnaud <alex.arnaud@biblibre.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Martin Renvoize <martin.renvoize@ptfs-europe.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Tomas Cohen Arazi
Julian Maurice
Lari Taskula
Jonathan Druart
Martin Renvoize
Lari Taskula
Olli-Antti Kivilahti