API First: the link between websites and mobile sites

API First: the link between websites and mobile sites
API First: the link between websites and mobile sites


The concept of “API First” is sounding ever louder and clearer. And it is not only small startups but major companies that are beginning to adopt this strategy. The reason is clear: websites are undergoing a major turnaround. The arrival on the scene of new devices has displaced the original idea with which many companies are present on the Internet. They are now no longer websites and instead have become a platform that needs to be available on the largest possible number of devices: cellphones, tablets, TV and of course, computer browsers.

Although it may seem obvious, the API First strategy must start out with one very clear idea: to define the API internally, before any other development, whether the project is a website or a mobile app, or both. The resources to be used must be established beforehand. Historically, this has not always been the case. The API was created a posteriori to share and interact with already existing websites. This caused a number of complications as they were not optimized for this use, and meant a substantial amount of legacy code.

Common errors when creating an ad hoc API

Creating an a posteriori API has dramatic consequences. We can make mistakes like exposing a data model or internal structures to the rest of the world, which reflects our own restrictions and architecture.

As soon as it becomes available to developers (the API consumers) they will have adapted to that implementation. By failing to define a clear distinction between API and internal architecture we will have lost the flexibility to make changes in our internal application without affecting our API users. An API goes beyond exporting certain data or interacting with them. It is a public layer that protects our internal implementation.

API First: the strategy for linking the website and the apps

API First fits the focus on the re-utilization of business rules and platform components, differentiating internal and external implementation. On this basis, websites and mobile sites share a common strategy, in addition to progressively developing the functionalities incorporated in our app in a more agile way. We move away from the primitive concept of merely displaying data toward a single model that is more focused on interaction.

API First must open a common communication flow to enable communication between both parties:

●      A shared language at all levels. It should not be restricted to developers alone –product managers, designers and stakeholders should also make decisions about the definition of the API. Both the data model and the business rules are transferred to that API, involving acceptance criteria for each app developed around it.

●      Delegation and responsibilities. The API must be an enabler, and smooth the tensions between the technical and business component. The API must be defined to reflect these undertakings. The part shared by the website and mobile site is delegated to the API.

●      Clear target for use. Combining the previous points, we must now define the scope of use and the practical application for this API, providing an app with content and interaction  which serves as an external API so developers can use it for their own mashups, and so on.

●      Distinction between the public and external layer of the API. It must incorporate mechanisms for security and the control of use by external users such as OAuth or token.

Defining an API: How to formulate it?

The prior design of APIs requires the use of tools that take into account usability, the needs of the applications/developers that are going to use it, that allow the creation of testable mocks and enable versioning, and –of course– the joint and ongoing creation of the documentation.

API Blueprint, RAML and Swagger are three excellent tools for designing APIs, which are becoming de facto standards. Then we can design the definition of the API on paper in JSON format or using markdown to describe the interface, structure and data model.

To interact with a previously defined API there are other tools like Postman or PAW, which generate an API Sandbox to interact with API REST collections.

More information on APIs here.

Follow us on @CIBBVA

It may interest you