Why an API – The problem
In developing the FE Skills Window, an application that will offer access to a range of Jisc resources for Further Education, we were faced with some interesting problems. We needed to come up with a unified way of accessing disparate resources, or the application would have to “talk” a series of dialects, one for each service.
We decided that the aggregation of the various resources would be achieved by utilising Elastic Search. This meant that talking one “dialect” for all content services was essential.
In addition to technical uniformity, an extra challenge had to be met; the curriculum and subject area mappings of different kinds of services. Again the ideal would be for all resources to expose the same kind of curriculum and subject area related properties in consistent way.
At the time only Jorum provided a REST API, whereas Hairdressing Training didn’t, and so we decided that an API to cover these two services would be a good starting point. We felt that a uniform PHP API would allow us to quickly develop the FE Skills Window application, as it will consume it whilst at the same time allow the Elastic Search indexing to take place, without it “knowing” the difference between the two services.
An extra benefit of this approach is that, being open source and available on open source code repositories, it could potentially encourage 3rd party developers to explore and use the various Jisc resources. We are hoping that the features of the implementation and its detailed documentation will increase its chances of adoption by other developers.
Warning: this is where we get into further technical detail, so read on if you need to understand how we are going to implement the PHP API!
The PHP API for Jorum and Hairdressers Training was created with the following goals.
- To provide a modern, Object Oriented PHP API for accessing the two resources.
- To be easy to install and use.
- To abstract and unify access to the two different resources (more to come).
- To become a building block for the release of additional APIs such as Mediahub and eBooks.
- To allow Elastic Search indexing of our resources through a unified interface.
In order to achieve those goals the two APIs were developed following the latest PHP proposed or accepted standards, specifically PSR-0 (autoloading) and PSR-1 (coding standards). Additionally, the API is implemented as a Composer downloadable package. That means that it can be dropped in any project that follows namespaces and uses Composer.
The coding standards compliance and extensive use of “docblocks” mean that when using an IDE that “talks” PHP you get auto-completion for the various classes and methods, as well as code hints. The idea is that one shouldn’t have to know the whole API by heart and in advance in order to use it. The API documentation is available on Github and can be also viewed online.
To make it easy to install and use the code is organised as a Composer package and hosted on Github. It means that installing it simply involves adding a few lines in a configuration file and running composer install or update.
The composer.json file for this install was as follows:
Currently the API uses some facilities provided by Symfony2 and Laravel, however we are working fast to remove these two dependencies, as they are superficial. This is planned for release 1.0 which is coming soon.
By implementing the Jorum API in PHP, that is reading it, creating native PHP objects and then outputting in various formats, we are in a position to adjust the output or add properties without changes in the core API. We also have the added flexibility of been able to use caching systems like REDIS, should performance become an issue. With Hairdressers training, which is based on Drupal, the advantage is that it now “talks API” in a unified way. Extra fields for Curriculum Mapping and Subject Areas were added using the build in Drupal functionality and exposed by the API just as they appear in Jorum. We feel that this approach will allow us to provide a single interface, through a uniform access point, for more resources in the future. Finally, the API is designed to support versioning.
The image above show Hairdressers Training Collections – a concept that doesn’t exist in the actual Drupal application.