In the proposed API approach we use best practices for design, such as consumer-oriented design, contract-first design, iterative design and simulation-based design. In the following, we introduce these best practices and show why and how they apply to API design.
Consumer-Oriented Design Approach
There are two basic methodological approaches. They are known under the names inside-out approach and outside-in approach, depending on the starting point and the direction of the design process. We propose the outside-in approach because it is consumer-oriented. We mention the inside-out approach as well to contrast and clarify the differences.
Inside-out Approach
The starting point for the inside-out approach is an analysis of what already exists inside the organization of the API provider. For API providers, the backend systems already exist inside the organization and are used as a basis for defining the API. The design of an API developed with the inside-out approach will closely resemble the structure of the backend system. Using this approach, an API could be built just by forwarding calls to backends, optionally some data format transformations and some protocol transformations.
This approach is quite simple from the perspective of the API provider, since the functional scope of the API is confined by one backend system. The complexities of aggregating information from multiple backend systems are reduced. For the API provider this approach might seem to be the natural choice.
Even though building the API may be simple from the perspective of the API provider, it might be quite complex to use the API for the API consumers, since they are confronted with the complex data structures of the backends. Such an API is not likely to be consumer-oriented.
Outside-in Approach
In a way, the outside-in approach is the opposite to the inside-out approach. The starting point for the outside-in approach is an analysis of what is needed by the consumers. The consumers are outside the organization of the API provider, thus the API provider needs to start the design process outside her organization. Only in the last step of this approach, the API provider may make considerations about what is inside the organization: the data formats, and the connections to existing backends.
The consumer-oriented approach described in chapter [chap:Consumer-Oriented-API-Design] is an outside-in approach. So why is a consumer-oriented API important? A measure for the success of an API initiative is the wide-spread use of the API: the API should be used by as many consumers as possible. To maximize the uptake of APIs with potential consumers, to maximize the active usage of the API and to maximize the integration in third party apps, the API needs to be as simple as possible from the perspective of the consumer. It certainly means more work on the side of the API provider, but there is a bigger chance that the consumer gets an API, she actually like to use.
The basic idea of the outside-in approach is to focus on the consumers. One needs to identify the target consumers first and then get to know their needs. This allows for designing an optimal experience for the interaction between the consumer and the API. For the API provider it is thus important to ask: What would the consumer want to achieve by using the API? How can I make it easy for the consumer to find the API? How can I help the consumer to build apps with my API and make it convenient for the consumer to use the API? Check out chapter for the details of this approach.
Contract-First Design Approach
In contract-first design, the central artifact is an explicit contract between API provider and API consumer. Such a contract is either dictated by the provider – or better – it is specified by provider and consumer together. In this contract, the API provider guarantees to provide APIs to the consumer, exactly as they were specified in the contract. Based on this contract, the consumer can already start implementing a solution before having access to the API.
Agile Design Approach
Agility is based on the premise that you can start without having a full set of specs. You can always adapt and change the specs later, as you go and as you have learned more. Through multiple iterations, architectural design can converge to the right solution. If the iterations are performed based on the architectural blueprint and not based on a full implementation, architecture improves the overall efficiency of development. But, is the agile approach 100% compatible with the requirements for APIs?
Before publishing the API, the API can be changed without constraints and the agile approach can be used. Change is easy and possible at any time.
After publishing the API, it becomes more difficult to realize changes. If a published API changes, clients may break. New versions need to be created for each API change that is not backward compatible. The interface specs are fully defined and thus the prerequisites for agility are no longer given. See section for more details on evolution and versioning of APIs.
An agile approach should only be used, until the API is published for the first time. Once the API has been published, changes need to be controlled more strictly and agility is confined to new versions of the API.
Simulation-based Design
Basically, every software system has dependencies to other software, such as other software components, libraries, and frameworks. Due to these dependencies, some components cannot be developed until the development of their dependencies has been completed. The consequence is sequential development of the components, a long development time and a long time-to-market for the complete software system.
Simulations offer a solution: they make it possible to break up the dependencies between software components and allow for integration and development of software components, even though their dependencies have not been developed, yet. Dependencies are replaced by simulations.
In API design there are two use cases for simulations:
• The simulation of backend systems allows for developing APIs without fully implemented backend systems.
• The simulation of APIs allows for developing apps (or other API solutions) without fully implemented APIs.
Both types of simulations have their place in API design – but in different scenarios. In the following sections we look at each of these two types of simulations in more detail.
Simulation of Backends
Since APIs depend on the backend systems and their behavior, the implementation of an API can only start after the backend has become available. If the backend has not been finalized yet, the development of the API is blocked and the API cannot be built.
Simulations of backend systems can be used to support the development of APIs. Backend simulations break the dependencies from APIs to backends. If the real backend is not available yet, a simulation of the backend can be used in its place. Since the behavior of the simulation is the same as the behavior of the real backend, the implementation of the API with a simulated backend can proceed independently of the availability of the implementation of the backend.
Simulation of the API
The development of an API solution, such as a mobile app, depends on the availability of the included APIs. If the APIs are not available, the development of the mobile app is blocked.
Simulations of APIs can support the development of mobile apps, which depend on the APIs. Even though the API has not been implemented yet, the mobile app can be built and the API can be integrated. The development of the API and the development of the mobile app can take place in parallel. The simulation speeds up the development time of the overall API solution, and allows for short time to market.
Simulation-based design of APIs and the contract-first design for APIs actually go hand-in-hand. The contract for the API can be used as a specification for the simulation.