Fall 2016 Sprint Report: REST API

November 16th, 2016 by  | Comments Off on Fall 2016 Sprint Report: REST API

Special thanks to this group’s participants: Brian C, Antti K, Kassim M, and Alec S!

During the Fall 2016 PKP Sprint event in Fredericton, New Brunswick, one of the tasks we decided to work on was the development of a REST API for OJS 3.0.

REST APIs are a perennial favourite subject — we’ve worked on this before at past events, and spoken with numerous users and partners in order to gather requirements for what the API should cover. (We’re still collecting these, so if you’re interested, please contact us to add details!)

Rather than get too mired in development, we opted to solve a few necessary but compact problems:

  • What general principles should we establish?
  • How will REST-style services be added to the existing PKP software stack?
  • What tools are out there to help us maintain, document, and test the API?

We were able to make significant progress toward each of these, and while we haven’t yet merged the results into the OJS software, we hope to do so and start implementing specific API interactions soon.

General Principles

Beyond the general principles for implementing a good REST API, we were able to establish a few specific guidelines:

Prepare for rapid iteration

Because we’re planning to add an API to an existing large application, the chances that we’ll get the API mapping correct on the first try are nonexistent. Instead, we should plan to build a strong, standard substructure and expect to add and rearrange endpoints fairly rapidly. Clearly versioning the API (e.g. including “v1” in the base URL for the first revision of the API) will allow us to clearly indicate when/where compatibility has been broken.

Avoid reinventing the wheel

OJS includes its own web framework, but that framework doesn’t provide standard REST-type services. Implementing these from scratch would be a waste of time and effort as there are plenty of third-party libraries and toolkits providing these capabilities. PKP has been attempting to reduce the amount of code it maintains, instead integrating other FOSS software, particularly as OJS 3.0 now makes use of standard deployment tools like PHP’s composer. Some preliminary API work undertaken in the summer resulted in an experimental integration of the Slim microframework; the group opted to continue with this integration.

Avoid parallel structures

The framework built into OJS includes a number of deeper structures, such as authorization and authentication policies, session management, provisions for URL rewriting, etc. The more these structures require reimplementation to expose features via the API, the more excess code and fertile ground for bugs it represents. In our experimentation we hoped to establish patterns that would avoid this.

Adding REST APIs to an existing application

Fortunately the choice of the Slim microframework allows us to preserve the ability to reuse the parts of OJS that we need with minimal implementation changes, while facilitating the addition of REST API services.

With approximately 500 lines of code, we were able to add support for a new URL namespace for the API, integrate the Slim microframework, and add a sample API interaction:

This is currently a work in progress — we will need to experiment a little further as we implement a few more sample interactions, to ensure that things like authorization policies don’t have to fragment into different behaviors overmuch. Currently, for example, the authorization policies need to get various kinds of identifiers from the URL in order to locate the required entities, and the IDs will appear in different places depending on whether the policy is being called from a page, or a component, or now an API. There are opportunities for improvement here.

The sample interaction exposes submission metadata in JSON-encoded Dublin Core or MODS.

If your journal’s URL looks like this:

http://[my-domain]/index.php/myJournal

…then this implementation adds a new URL namespace called API, e.g.:

http://[my-domain]/index.php/myJournal/api/v1/submissions/[submissionId]

Testing & Documentation

In order to ease maintenance and ensure the stability of the API, we were interested in identifying tools that could help tackle self-documentation and testing. We identified Swagger/OpenAPI as a leading contender. Their pet store demonstration illustrates the tools potentials handily.

It’s also possible to integrate this tool with our existing continuous integration testing toolset, using SwaggerAssertions.

Next Steps

This work provides a basic platform for API interactions to be introduced to OJS 3.x. As the expansion potential for the API is almost boundless, we’ll be focusing on the simplest and most-requested interactions first, and gradually expanding towards complete coverage of the use cases we’ve collected. We hope to start shipping the API with OJS 3.1 (and OMP around the same time).

Comments are closed.