The two perspectives of API design
API design is a matter of point of view, an API can be designed from two perspectives: outside in and inside out. While the outside in approach focuses on creating an API from the consumer point of view regardless of what happens behind the API; the inside out one focuses on giving consumers direct access to the engine behind the API. The outside in approach is usually praised as better than the inside out one to design an API. But is this an absolute truth? Is this only a binary problem? This is what we will discover in this article.
The outside in approach
When designing an API, the most recommended approach is the outside in one. The API designer focuses on the consumer's point of view regardless of what happens behind the API. The consumer is left totally unaware of the inner-workings of the API, of its implementation.
The purest form of this approach is to provide an interface that offers functionalities in a generic way that may fit a broad range of consumers. Any public API should be designed with this purpose in mind.
Gocardless or Stripe provide APIs abstracting the complexity of payment systems for any consumers with a 100% functionality centric design.
On the opposite, an API could be specifically designed for a consumer. This "extreme" is usually used for private APIs to achieve a certain efficiency by aggregating data to diminish the number of API calls for mobile applications or proposing specific data representations to match specific website pages for example.
Netflix provides specific APIs for its various consumers through BFF: Backend For Frontend (also known as an Experience API). Each BFF relies on netflix's core API and is developed by the consumer team to expose an adapted API matching exactly the consumer's needs.
The inside out approach
Often pointed out as a bad pattern, the inside out approach focuses on exposing what's inside the box as an API. Used recklessly it can lead to a total disaster but in some contexts, what's inside the box is valuable in itself (almost) as it is.
An inside out designed API can be difficult to use as it exposes internal complexity only understood the the underlying system experts. It can also be difficult to evolve as it is tightly coupled to this system.
But sometimes for internal APIs, administration APIs or proof of concepts for example, we can afford the shortcomings of this pattern. Who had never needed a simple CRUD API to work directly on a database or even a Google Sheet?
The middle path approach
As always, there's no ultimate truth, no silver bullet. In API design, the outside in and inside out perspectives are not mutually exclusive and each side is even not absolute. This could be called the middle path approach.
When using the outside in approach, and focusing on the consumer point of view, the resulting design still have to be confronted to existing underlying system, to what's in the box, because the API is only an interface to this system.The design may need to be adapted to avoid too much evolution, complexity or stress on the implementation for example.
When using the inside out approach and exposing a system as it is, the resulting API still needs to be used by consumers and the people who build them. The design may need to be adapted to avoid too much complexity or number of calls for example.
Each side is not an absolute one. The outside in approach cursor will move from 100% generic to match the largest range of consumer to 100% specific to fulfil the specific needs of one. The inside out approach cursor will move from 100% transparency, unvarnished exposition of the underlying system to 100% opacity.
Where to put the cursors on both outside in and inside out approaches will depend on the context in which the API is designed.
In the next post of this series, you'll discover a key concept in API design: consistency.