Bug 21116 - Add API routes through plugins
Summary: Add API routes through plugins
Status: RESOLVED FIXED
Alias: None
Product: Koha
Classification: Unclassified
Component: REST api (show other bugs)
Version: master
Hardware: All All
: P5 - low new feature (vote)
Target Milestone: ---
Assignee: Tomás Cohen Arazi
QA Contact: Alex Arnaud
URL:
Whiteboard:
Keywords: release-notes-needed
Depends on:
Blocks:
 
Reported: 2018-07-25 13:56 UTC by Tomás Cohen Arazi
Modified: 2018-11-29 13:45 UTC (History)
9 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Bot Control: ---
When did the bot last check this:
Who signed the patch off:
Text to go in the release notes:
Allows the extension of the Koha API via plugins. This can allow for custom vendor integrations and prototyping of new routes.


Attachments
Bug 21116: Add API routes through plugins (8.84 KB, patch)
2018-07-25 22:28 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 21116: Add API routes through plugins (8.90 KB, patch)
2018-08-08 22:33 UTC, Benjamin Rokseth
Details | Diff | Splinter Review
Bug 21116: Unit tests (7.60 KB, patch)
2018-08-27 19:32 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 21116: Add API routes through plugins (9.30 KB, patch)
2018-08-27 19:32 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 21116: Unit tests (7.66 KB, patch)
2018-08-31 07:32 UTC, Alex Arnaud
Details | Diff | Splinter Review
Bug 21116: Add API routes through plugins (9.35 KB, patch)
2018-08-31 07:32 UTC, Alex Arnaud
Details | Diff | Splinter Review
Bug 21116: Unit tests (7.73 KB, patch)
2018-09-10 18:47 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review
Bug 21116: Add API routes through plugins (9.36 KB, patch)
2018-09-10 18:47 UTC, Tomás Cohen Arazi
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Tomás Cohen Arazi 2018-07-25 13:56:08 UTC
We should have a way to add routes using specially crafted plugins.

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

Plugin-generated routes will be placed inside /contrib/<namespace>, where <namespace> is what the 'api_namespace' returns.
Comment 1 Tomás Cohen Arazi 2018-07-25 22:28:17 UTC
Created attachment 77274 [details] [review]
Bug 21116: Add API routes through plugins

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, wait a bit more for those samples :-D
Comment 2 Tomás Cohen Arazi 2018-08-02 10:07:40 UTC
The KitchenSink plugin [1] already implements a sample contrib endpoint using this :-D

YAY!

[1] https://github.com/bywatersolutions/koha-plugin-kitchen-sink/commit/e7da3c40842b25d3ef88bf7600c7c1113365b8d2
Comment 4 Benjamin Rokseth 2018-08-08 22:33:32 UTC
Created attachment 77601 [details] [review]
Bug 21116: Add API routes through plugins

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, wait a bit more for those samples :-D

Signed-off-by: Benjamin Rokseth <benjamin.rokseth@deichman.no>
Comment 5 Benjamin Rokseth 2018-08-08 22:41:54 UTC
Tested according to plan:
patched, added kitchen sink plugin, verified swagger schema and new 'contrib' endpoint  :
PUT /api/v1/contrib/kitchensink/patrons/{patron_id}/bother

gave expected result: {"bothered":true}

A very interesting and non-obtrusive approach to a common problem (feature creep)!
Comment 6 Tomás Cohen Arazi 2018-08-27 19:32:16 UTC Comment hidden (obsolete)
Comment 7 Tomás Cohen Arazi 2018-08-27 19:32:25 UTC Comment hidden (obsolete)
Comment 8 Alex Arnaud 2018-08-31 07:32:52 UTC
Created attachment 78322 [details] [review]
Bug 21116: Unit tests

This path implements unit tests for the route-from-plugin development.
It adds the required methods to the Koha::Plugin::Test plugin
distributed along with the tests. A second plugin implementing invalid
OpenAPI specs is added (Koha::Plugin::BadAPIRoute).

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Alex Arnaud <alex.arnaud@biblibre.com>
Comment 9 Alex Arnaud 2018-08-31 07:32:59 UTC
Created attachment 78323 [details] [review]
Bug 21116: Add API routes through plugins

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>
Comment 10 Tomás Cohen Arazi 2018-09-10 18:47:47 UTC
Created attachment 78542 [details] [review]
Bug 21116: Unit tests

This path implements unit tests for the route-from-plugin development.
It adds the required methods to the Koha::Plugin::Test plugin
distributed along with the tests. A second plugin implementing invalid
OpenAPI specs is added (Koha::Plugin::BadAPIRoute).

Edit: I made terminology changes to make it less rude.

Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Alex Arnaud <alex.arnaud@biblibre.com>
Comment 11 Tomás Cohen Arazi 2018-09-10 18:47:52 UTC
Created attachment 78543 [details] [review]
Bug 21116: Add API routes through plugins

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>
Comment 12 Nick Clemens 2018-09-14 19:59:06 UTC
Awesome work all!

Pushed to master for 18.11
Comment 13 Martin Renvoize 2018-09-20 11:12:58 UTC
Pushed to 18.05.x for 18.05.04.

After deliberating on this one for a while, I've decided to backport it for similar reasons to bug 20942.  It is not immediately user facing and as such will not be a surprise to end users.  It does, however, encourage plugin developers to develop and test against a stable koha earlier and open up the option for a wider supported koha version range in plugins.
Comment 14 Fridolin SOMERS 2018-09-24 10:33:43 UTC
New feature not pushed to 17.11.x to encourage upgrade ;)
Comment 15 Fridolin SOMERS 2018-11-29 13:45:16 UTC
(In reply to Fridolin SOMERS from comment #14)
> New feature not pushed to 17.11.x to encourage upgrade ;)

I changed my mind, plugins are great, it does no harm to have this in 17.11.x
I haded a followup to remove use of Koha::Exceptions::Exception that needs Bug 20590.

Pushed to 17.11.x for 17.11.13