API Development best practices

API (Application Programming Interface) is a software intermediatory that facilitates communication between two applications. For example, when you use a weather application to check the weather forecast, the application uses an API to communicate with the backend to retrieve that weather-related information.

In the above diagram, the web application in the web browser uses the internet to request some specific details via an API. API talks to the backend web server connected with the database to retrieve information.

Different categories of API

Based on the audience of an API, you can categorize APIs as follows:

1. Public APIs

Public APIs are called open APIs. These APIs are made available to anyone and everyone who agrees to their terms of service.

2. Partner APIs

When you are trying to focus on business development, partner APIs are coming into the picture where these can facilitate greatly.

3. Internal APIs

With the exact characteristics of a modern SOA (Service Oriented Architecture), the internal APIs help reuse the APIs between several teams. Internal APIs are created for the developers of the same company.

4. Microservices APIs

Microservices APIs are created to communicate between individual services inside the same application.

Microservices APIs

In the above diagram, the client apps, which are mobile, or web use separate microservices API calls to perform a business use case or a logic.

In a monolithic application that runs on a single process, the components invoke each other using functional calls. These functional calls can be strongly coupled if you are writing the objects within the code. It can be decoupled if you are using dependency injection by referencing abstractions. Whichever the situation is, the objects are running within the same process.

The significant change and the challenge in moving from monolithic application to microservices architecture lie in the communication between the independent microservices components. A microservices-based application is a distributed system running on multiple processes and services. In most cases, these multiple processes and services are across multiple servers and hosts. You must consider that each of these service instances is a process. In this case, the individual services must interact using communication protocols that are inter-process. These protocols can be HTTP, TCP, or AMQP, depending on the nature of each service.

Areas to consider when developing APIs for microservices

1. Performance

It is crucial that everyone remembers and understands why the developers want to move from a monolithic approach to the microservices architecture. The reason is to develop, maintain and deploy each service independently. However, an API call to a microservice will result in many calls between different microservices depending on the business use case and logic. Therefore, it is essential to focus on the performance aspect if you want to achieve the same level of monolithic application performance that has rapid communication between the same process.

Solutions

• Using binary inter-process communication protocols like gRPC
• Using JSON over HTTP
• Good API design which supports interoperability
• Design non-chatty interfaces which do not use back and forth
  communication to accomplish a particular task.

2. Loose Coupling

Another important aspect of moving into microservices architecture is getting the maximum benefit from loose coupling that allows independent development and re-usage.

Solutions

• Even though it is difficult to anticipate the future business logic and use cases, it is vital to design the APIs with room to grow and evolve.
• Using message-oriented design pattern and Hypermedia

3. Domain Modeling

If the purpose of the API is not to provide insights to the backend of a system, it should always have some abstraction over the underlying storage.

Solutions

• A persistent layer should be present and evident if the microservice is stateful.
• Have specifically designed API for the transformation of the domain model.
• Every microservice should be dealing with the information it needs only.
• Usage of shared domain models.