API first: first things first

What is API first?

The API-first approach focuses on planning the API through a design contract using RAML or OpenAPI. This contract ensures consistency, reusability and interoperability in the API. It allows using free tools to create documentation and tests based on the contract specifications.

The problem of not planning APIs

If you have ever required an API as an alternative for communication between applications on your web project, or you have simply worked on the development of this type of service, it is very likely that you followed the same pattern of many developers, starting by the immediately writing of documents and documents of code with little or maybe none planning in advance.

Final result: your API will be ready in a short period of time if you don't have too many obstacles in the way, so all the parties involved in its usage will be able to consume it if, and only if, they understand how to do it.

You probably refuse my point arguing: “No problem, all the code documents have annotations, comments and I am even working on a manual description for using my API from scratch, so the parties that need to use it will find how to do it easily.”

Well, what about validation tests? They will surely be carried out once the implementation of the API is finished and at this point, a loop of corrections, rewriting and updating of annotations will start; a significant overload that, in most of the cases, it would have been unnecessary if a little prior planning and simulation tests were conducted with the active interaction of all parties.

Not to mention the obstacles or delays that might arise in the future if the project further scales.

This right away hands-on-code approach, or "code-first" as it's well known, is increasingly dying out when APIs are not integrated by just a few endpoints nor conceived for the internal work team consumption. Thus, what is the proper way for implementing an API?

API-first and API-design first

Nowadays, emerging approaches are reaching for the planning in advance and specification of design contracts for APIs, which must satisfy the business logic in a sustainable and scalable way.

Remember that an API is nothing more than the common language that all the parts of a project will use to communicate to each other, and therefore, it must be understood, agreed, specified and validated upon the all development team.

You have probably heard before about terms such as “API-first” or “API-design first”. But, what is the meaning of these terms? Are they not the same thing? No, they are not.

The API-first approach gives more priority to API planning based on the specification of contract in languages such as RAML o OpenAPI. Starting your implementation with a predefined contract ensures consistency, reusability, and a broad interoperability of the resulting API, being possible to explore the advantages of free tools for documenting and testing it according to the contract specifications.

On the other hand, API-design first is a more ambitious approach in terms of planning. Before starting to write any line of code or specification, the technical and non-technical parties must be able to discuss the functionalities of the API, define the structure of the contract, carry out operational simulations and conceive the possible validation tests. All of this must be accomplished in resonance with a short feedback loop. Next, the approved API contract will be implemented, and from this point on, frontend and backend developers,as well as quality testers, will be able to implement all the applications and tests in parallel, with additional documentation support and testing environments.

Since these two approaches emphasize the importance of design documents and contracts, Redsauce Engineering staff recommend you combine both approaches. After all, once you implement one of them you indirectly have run half of the way to implement the other, the main difference relies on the order you fix for the tasks. Just think about it, the “API-first” and “API-design first” approaches share a common group of stages where the sequence for executing the stages makes the differences among them.

Combining API first and API-design first approaches

Saying so, how can you combine both approaches?

Well, start by planning and specifying your API code, in a process that flows in parallel with the active discussion and validation of the operations, structures and examples of the contract by the involved parties. Next, make the corrections and once the contract is well defined, go ahead with the processes of documenting, setting testing environments and developing tests.

Nowadays, taking advantage of tools like OpenAPI and Postman for addressing these approaches during API development is simpler than ever, but this is a topic for a coming post!

Remember that if you, or your team, need help with your API tests, at Redsauce we are specialists in automating them and integrating them into development pipelines. You can see more in this link