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>
borrowernumber parameter is no longer required and you can filter on
every column of reserves table
Some example requests
- GET /api/v1/holds
- GET /api/v1/holds?biblionumber=123
- GET /api/v1/holds?borrowernumber=456
- GET /api/v1/holds?priority=0&found=W
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
GET /holds?borrowernumber=X (list)
POST /holds (create)
PUT /holds/{reserve_id} (update)
DELETE /holds/{reserve_id} (delete)
Unit tests in t/db_dependent/api/v1/holds.t
Signed-off-by: Jesse Weaver <jweaver@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
GET /reserves?borrowernumber=X (list)
POST /reserves (create)
PUT /reserves/{reserve_id} (update)
DELETE /reserves/{reserve_id} (delete)
Unit tests in t/db_dependent/api/v1/reserves.t
Test plan:
1. Apply patch
2. Run unit tests
3. Play with the API with your favorite REST client, using documentation
in the swagger.json file
4. Try to make reserves until the maximum number of reserves for a user
is reached (you should have a 403 error)
Depends on bug 15126
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
Signed-off-by: Jesse Weaver <jweaver@bywatersolutions.com>
Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Remove the use of soon to be deprecated x-mojo-controller from our
specification and replace with the recommended operationId format.
Signed-off-by: Benjamin Rokseth <benjamin.rokseth@kul.oslo.kommune.no>
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>
Also, complete the Swagger definition of a patron
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: 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>