Design Reliable APIs
In the era of transition from monolith applications to microservices based architectures, communication is the key to success. Moving from monolith to microservices involves moving a lot of complexity to the network layer, so is important to do communication between components in a reliable and resilient way.
Monoliths vs. Microservices
Here is approximately nothing new. Big companies like Netflix or Google are doing lots of research in this field because they faced these problems years before us. They publish lots of best practices about how to implement this transition as smooth as possible, all you need to do is to combine all these best practices and build a “frame” that fits for your organization.
Another helping factors are Cloud Native Technologies. Nowadays, thanks to these things, spinning a new microservice is piece of cake in comparison with the process needed in the monoliths ages. Simply throw your code to your container orchestrator and it will know what to do for you, instead of talking with some Ops guy to deploy a new VM, configure some web server and put your code there.
The natural growing of microservices based on APIs
The main idea is to expose an interface to a uniform API. Here shows up a small problem of semantics… People tend to expose APIs based on their programming languages preferences. If you have, for example, a microservice written in golang, you will tend to expose a golang friendly API. The key to build a reliable API is to avoid collisions and inconsistencies. Until now, the first observable characteristic of a reliable API is idempotency.
Ways to design
There are lots of ways to design an API. And this can be very confusing sometimes. If we look at some buildings belonging to the same architectural style, we will quickly observe they have some common characteristics but everyone is unique in its way. This example is applicable to the APIs too. Going deep with this analogy, if you look at a building and extract the common characteristics, you will know what architectural style was used. The same goes with APIs. There are patterns shared between systems and there is no way to say if architecture is good or bad.
Some general principles to follow when designing an API
Document your API
This is the most important aspect when you build an API. You build the API to be consumed by clients. This is your main goal. So, for a client to be able to consume your API, it needs to know and easily understand how your API works. So, each and every time, good documentation means good API!
Build consistent APIs
One of the struggles when building an API is to keep it consistent. Consistency means that similar endpoints should have similar behaviors. Keep your URL structure, the responses structure or the HTTP verbs consistent over the entire API. This will make it easy to be used because the client will be able to anticipate. If everything is consistent, the client's code will be cleaner and easy to maintain and test, so the key to a reliable API is consistency.
Keep it simple
Keep it simple and do it well by respecting universally accepted standards and tools. This will add a plus of reliability to your API. An important thing when we speak about the reliability of an API is interoperability.
Use versioning for your API and keep clients up to date
Things are moving very fast, so new features are constantly added and old ones are improved to be more performant and reliable and the features no more used are decommissioned. In this ecosystem characterized by dramatical changes, you need to make sure that your clients do not suffer.
Implement ways to share multiple features in place at the same time and always inform your clients about the changes. Always keep in touch with clients. Use metrics to have a clear view of the usage of the system and make sure you can answer questions like “what users call a specific endpoint?”.
Avoid breaking changes and this will keep your clients happy. Happy clients combined with good performance, stability, and consistency mean reliable API.
