Great applications are built on forgettable APIs

Written by Vaadin Leif Åstrand

An API is an interface that application developers use to make their application interact with some other application, or another part of the same application if it has modular structure. The purpose of this interaction is to transmit some kind of data between the applications, such as fetching the latest weather forecast or submitting tax records to the appropriate authorities. The API defines how the data should be structured in different types of messages sent between the communicating parties.

At the end of the day, the purpose of data and applications is to serve the needs of human users. The relationship is sometimes only indirect in case there are multiple intermediate applications passing data between each other before it reaches the application that the user is using. Since humans and computers have quite different means of communication, a different type of interface is needed instead of an API. This is the user interface, or UI.

From the point of view of an application user, the UI is all that matters. Everything else is an implementation detail to them. They only care about getting their job done as efficiently as possible, but they aren’t concerned about how that is carried out. API use matters no more than any other technicalitty such as which programming language is used to implement the application or what kind of hardware is used to host any server-side functionality of the application.

Application developers serve their users

It is the application developer’s job to make all of this come true for the end user. They should design and implement the UI based on the needs of the user and not based on what’s convenient with the APIs they are using. If the API uses a weird format or structure for its data, then the application should take care of converting that to something that makes sense for the user. If there is a risk that the API isn’t always available, then the application developer should ensure suitable fallbacks are in place. Finally, the application needs to mitigate the risk that the API might change in the future.

From a more practical point of view, this typically means that the application should use an anti-corruption layer between the API and the rest of the application. This makes the API quite forgettable since developers working on other parts of the application won’t have to remember all the details that are encapsulated in the anti-corruption layer. Encapsulating the API does also have secondary benefits such as making testing easier.

Dealing with potential reliability or performance issues with an API leads to some additional considerations. At the very least, the application needs to have timeouts or circuit breakers in place to deal with the unexpected. If circumstances allow, it’s also very beneficial for the application to have a local caching layer to further isolate the user from the API. It’s also essential to design the UI in a way that any problematic situation is clearly understandable to the user. Anything that can go wrong will go wrong, eventually.

It’s lots of work for the application developer to do all of this, but it’s their job. Otherwise, the user might just as well use the original API as-is and the application would thus be worthless. The biggest challenge might be how to know when enough is enough.

API providers serve application developers

It is the API provider’s job to make all of this come true for the application developer, and by extension also for the end user. It will be easy for the application developer to implement an appropriate anti-corruption layer if the API is well designed. The same also goes for dealing with potential reliability and performance issues.

This means that the provider should follow good practices for API design. Calling conventions should follow established patterns. Data should be structured in a logical way with intuitive names. Performance and availability should be sufficient and consistent.

The API should do its thing as expected without causing surprises for the application developer. This in turn makes the API forgettable.

It’s still worth it

All of this sounds like an awful lot of work for everyone involved – except the user who just gets to enjoy a good UI design that works reliably. At the same time, the rewards are immense. That’s why software developers provide and use forgettable APIs despite the efforts involved.