Towards the creation of agnostic APIs

The modern trend in web development is to separate the views and the application logic into two completely independent environments.

This trend has been propelled by React or Vue.js, allowing the development of Javascript applications that communicate with remote services.

Classic architecture used in Headless CMS, for example.

At Octree we are used to developing applications using this method. This led us to reflect on another workflow, just as common: that of developing only the services and APIs without knowing the details of the UI or on which media the applications will be implemented.

Developing agnostic APIs would allow us to add existing functionality to projects without changing what has already been done. Moreover, it would allow the creation of synergies with other providers who would implement the UI of our services.

In the context of application development, service development gives the freedom to work with several independent teams together and to offer elegant transitions between providers in the event of a project switch.

Like all new ideas at Octree, we start by implementing a proof-of-concept (POC) to introduce the team to the idea and identify risks through a small project.

The problem: how to develop a service without knowing its future UI implementations

Formulation of the POC

Having already worked with Headless CMS in the past, we had a fear concerning authentication. Indeed, if the connection must be done on a mobile application and a web application at the same time, the infrastructure necessary to manage security could be complex. Moreover, if we stay in a session-based system, offline-first implementations could be compromised.

The second concern that came up in our discussions was creating a service that was flexible enough that application development would not be hindered by our APIs. The need to provide an API that can be modified quickly seemed to us to be the second key point of this POC.

Finally, it seems to us that the documentation is also one of the sensitive points, as it has to be explicit enough to allow developers to get to grips with our service while remaining up-to-date. This can be a big problem, especially if the APIs are going to change quickly - during an alpha release for example, where breaking changes can appear with each release.

POC API-Only

After some discussions around the topic, we set up an experiment to test our greatest fears.

As an administrator, I can log in to my admin area. As an administrator, I need to be able to manage member access. As a member, I can log in to my member area. As a member, I can see all members. As a member, I can edit my information.

This POC allows us to test session management, data retrieval, and editing. The example seems trivial, however, these two services should allow the connection of a large number of types of applications. We have chosen to use :

• Ruby on Rails with Postgres

• OAuth2.0 authentication and Json-Web-Token

• GraphQL and a GraphiQL interface

Authentication and GraphQL/GraphiQL will be the subject of two more articles to come. The documentation aspect will be partially covered, but a second POC may be necessary if we find this documentation support insufficient.

Conclusion

Taking a step back to consider what would be the essential proof-of-concept to test a new approach is not something easy. As the test is not yet on a pilot project, we will miss some critical points of the workflow, as we are far from a complex application.

Fortunately, our past experiences in creating APIs in conjunction with applications have taught us to keep an eye on these aspects.