Recommendations for APIs development

Aug 03 2018

Regarding the APIs and, more generally, the topic of exposure and access of data between automated systems, the “1st Report of the EOSC project on Data Interoperability” underlines the need for a balance between the multiplicity of solutions found in the context (pag 22: DCAT, OAI-PMH, RDF, Open Geospatial Consortium, RESTful API) and the opportunity to indicate a shared methodology (p 14: produce a set of guidelines and a data interoperability architecture proposal).

It is also rightly pointed out in the report that the EOSC project can not include development planning among its objectives: neither for Searching technologies (p 14: This work will not consider the technologies or tools that are used to search for data, but rather the data models, metadata and technologies describing how to expose pertinent metadata) nor for the collection of data between systems (p 14: This work it is not about how metadata catalogues collect data from data repositories but about how metadata catalogues expose metadata to EOSC users and services).

And, for situations where the APIs are not present and can not be developed (due to lack of resources), it is absolutely correct to suggest, as a priority, the insertion of simple metadata in the GUI HTML pages, based on widely used schemas like (p. 25: as an interim measure, we suggest that metadata catalogues and data repositories should at least expose structured metadata through a HTML mark-up vocabulary such as

But it is also true that a lack of programmatic interface for automatic systems has been detected (p 25: 30% of metadata catalogues do not provide a programmatic interface for services) and the recommendation is that data resources provide at least one programmatic interface (p 26).

And, together with the correct observation that a single type of API can not be imposed (p 25: It is difficult and maybe counterproductive to recommend adoption of just one specific type of programmatic interface for all the metadata catalogues), it is also noted that the best equipped stakeholders combine specific APIs with more generic and standardized APIs (p 25: many metadata catalogues provide both an interface tailored to their domain needs, and a more generic and standard interface).

Therefore, for future APIs developments (in the central catalogs to be potentially implemented, as well as in the current stakeholders repositories), general reference models could be suggested.

And, as well as the definition of a Data Interoperability framework in the EOSC is based on the FAIR principles (p 10: We base the definition of a Data Interoperability framework in the EOSC on the FAIR principles - data and services need to be Findable, Accessible, Interoperable and Reusable “FAIR Principles for Data Stewardship” 2016), in the same way the recommendations for the API could refer to some of the most widespread and documented paradigms, to be used only as a "functional model" (rather than as a specific type of programmatic interface).

The most appropriate reference, for the spread of its use, could probably be the REST architectural style, with its set of simple constraints for the implementation of web services.

In particular, among the 6 constraints of the architectural style (to be certainly proposed in their entirety), the main one to be suggested could be the use of “Uniform Interface” (Roy Fielding, doctoral dissertation, 2000: By applying the ... principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability) with the other specifications that it implies: “Resource-Based” (resources are identified by URIs, and the resources themselves are conceptually separate from the representations that are returned to the client), “Manipulation of Resources Through Representations” (when a client holds a representation of a resource, it has enough information to modify or delete the resource on the server, provided it has permission to do so) and “Self-descriptive Messages” (Each message includes enough information to describe how to process the message)