How should I design and develop my APIs? Many approaches to proper API design and development have been proposed and are still the subject of passionate debates. There is no right or wrong approach, but there is an approach that fits into a specific company culture better than others.
If we design APIs as reusable products and design them from the perspective of the prototypical API consumers, then we are on the way to build consumer-oriented APIs – APIs that our consumers will love.
This is why we present an API design and development approach consisting of some coarse granular phases that you can pick and choose from to ensure that the approach you use for your company actually fits your company culture. This is one of the best ways to make sure that the API approach is actually accepted and applied by the team. Look at the proposed approach as a guideline, which provides some goalposts along the way, that were constructed based on past failures, experiences, and learnings.
API Product Design
If we design APIs as reusable products and design them from the perspective of the prototypical API consumers, then we are on the way to build consumer-oriented APIs – APIs that our consumers will love.
The fundamental idea is to design APIs as a digital product in its own right. Being a digital product, the API needs to be consumer-oriented. Now what does that mean and who are the consumers of an API?
Learn more about API Product Design …
API Design
Any type of design requires taking well-informed decisions. The decisions are intended to make the product better in some way, e.g. provide more functionality, provide better quality, or a better user experience. Better design decisions typically lead to better products. This is no different when designing APIs. Which design decisions are there for APIs? We see four groups of design decisions.
Architectural Design Decisions
When designing an API, decisions have to be made regarding architectural issues, such as the patterns and the styles to be used. Should the API follow the REST or SOAP architectural style? These design decisions are foundational and have an impact on all following decisions. We will address architectural design decisions for APIs in chapter 5 of the RESTful API Design Book.
API Frontend Design Decisions
Since the frontend of the API is visible to the API consumers (= customers of the API), frontend design decisions are quite critical to the success of an API. Frontend design for APIs is typically RESTful design. For RESTful frontend design, we need to answer questions such as: How does the URI of the API look like? Are the parameters passed in the form of query parameters or path parameters? Which headers and status codes should be used? We will address frontend design decisions for APIs in chapter 7 of the RESTful API Design Book.
API Backend Design Decisions
The functionality of the API depends on leveraging data and services of backend systems. Backend design decisions address the connection between API and backend. Design decisions regarding the integration, transformation, aggregation, security and error handling of the backend have an impact on the functionality of the API. We will address backend design decisions for APIs in chapter 10 of the RESTful API Design Book.
Non-functional Design Decisions
The architectural, frontend, and backend design decisions are primarily taken to craft the functionality of the API. However, these decisions also have an impact on the non-functional properties of the API, such as security, performance, availability, and evolvability. Non-functional properties of the API should not be an afterthought. The API needs to be designed right from the start to fulfill non-functional requirements. We will address non-functional design decisions for APIs in chapter 11 of the RESTful API Design Book.
Applying the Right Methods
Since building consumer-oriented APIs with the outside-in approach is rather difficult for the API provider, as much methodological support as possible should be given to the API provider. This includes contract-first design, agile design, and simulation-based design.
Applying the contract-first ideas to API design allows for a clear separation of the responsibility between API and the client.
Applying an agile approach can help to navigate in situations with unclear or vague requirements, but should only be applied until the API is published.
Applying ideas of the simulation approach allows for breaking up the dependencies during development. It allows for independent development of client and API, despite the dependencies between them.
Our proposed API design approach, which is described in the following section, integrates ideas from all of these approaches.
Learn more about the Methods and Foundations …
Applying the Right Tools
When designing a new API, you need to make a lot of API frontend design decisions. You should capture these design decisions using an API description language, such as OpenAPI (a.k.a. Swagger) or RAML. And once an API has been designed, it needs to be communicated to team members, developers, product managers, architects, testers, and of course to the consumers. API design is often used to communicate between designer and developer or to communicate between provider and consumer. In a sense, the API design serves as a contract.
So the question is: How can I write down my API design? The answer is API description languages, such as the OpenAPI/Swagger or RAML. They can be used for expressing important aspects of the API design. Especially the frontend design decisions and architectural design decisions, which are visible to the consumer, can be captured by API description languages.
API description languages are also very powerful tools, that can be used for improving the efficiency of design and development through the automated generation of design and development artifacts. For example, they can be used for code generation of the API, code generation of the API clients, generation of documentation, generation of tests, and the generation of mocks.
Learn more about the OpenAPI language in chapter 8 of the RESTful API Design Book and the RAML language in chapter 9 of the RESTful API Design Book.
API Design Phases
Let’s start with an overview of the phases in this API design approach. Each phase of this approach consists of a creative part and a verification part. During the creative part, an artifact is crafted, during the verification part early feedback on the artifact is collected. In each phase of the design and development journey, feedback from the consumers is elicited. It is important to collect the feedback as early as possible when changes to the API are still possible, relatively simple and can be implemented with low risk, low effort, and low costs.
This design approach is meant to be used iteratively. There are small iterations that are triggered by the verification part of the same phase. And there are also big iterations, which are triggered by one of the later verification phases and require going back to the creative part of an earlier phase. Keep in mind, that in an iterative and agile approach, not all information and requirements about the constructed artifact need to be available in the beginning, but new and more detailed information and insights are gathered and integrated during each iteration. We need to get feedback from customers on the API design and build the API outside-in. This means we need to start from the needs of the API consumer towards the existing legacy systems. And not the other way!
This design approach is an outside-in approach and also incorporates ideas of contract-first design, the agile approach, and simulation-based development. In this approach, the contract is expressed in the form of an API description. In each step of the approach, an API description is either created, refined, or used: the API description is the red thread connecting all the steps of the approach.
Our proposed API design approach is organized into seven phases.
- Phase 0: Need Finding
- Phase 1: Business & Domain Analysis
- Phase 2: Architectural Design
- Phase 3: Prototyping
- Phase 4: Implementing for Production
- Phase 5: Publishing
- Phase 6: Maintenance
Phase 0: Need Finding
If you don’t really know what you want to build, but you want to serve your customers better, then starting with a customer-centric design thinking phase may be right for you. Just be ready for any outcome. Maybe building an API is not the best solution for your customers need.
More on API Design Thinking …
Phase 1: Business & Domain Analysis
Domain analysis should get us thinking from an API consumer perspective: Who are the consumers of the API? What is the purpose of the API? Which API solutions do the consumers plan to build with the API? Which other API solutions would be possible with the API? How does an API consumer prefer to interact with the data delivered by the API?
Phase 2: Architectural Design
In the architectural design phase, we choose a server architecture, an API philosophy (Service or GraphQL), and an architectural style (REST, SOAP, RPC) for realizing the API. Maybe you need to realize event? Then might want to consider Webhooks. However, these decisions also have an impact on the non-functional properties of the API, such as security, performance, availability, and evolvability.
More on Architectural API Design …
Phase 3: Prototyping
For prototyping an API we need to define an API description in OpenAPI, Swagger or RAML (or as a GraphQL Schema) and generate a prototype API. We use automatically created mock data, to simulate the response of the API and get some first feedback on the API design. In this phase, we can iterate multiple times by extending the API description and collecting feedback based on the mocked API.
Phase 4: Implementing for Production
When implementing for production, we gradually move away from the use of mocked data, towards real data and real backend systems. At this point, the accidental complexity of the organically grown legacy systems may hit us and the API developers. In the implementation phase, non-functional properties come into focus, such as stability, performance, and security.
More on Implementing an API for Production …
Phase 5: Publication
As soon as the API is published, it needs to stay backward compatible with the originally published version. Only backward compatible changes are possible. Knowing about this hard cut imposed with initial publication of the API, we need to ask if we have tested enough and have received enough consumer feedback to be confident to take the big leap of publishing the API.
Phase 6: Maintenance & Versioning
During the maintenance phase, bugs and issues may be resolved, but also new functionality may be introduced, as long as it is backward compatible: functionality and fields may be added without breaking clients, but removing functionality or fields is not permitted; a new version has to be created for such breaking changes.
Further down the line, we want to learn whether and why consumers use the API. We need to observe the metrics of our API to learn how consumers use the API. This cannot be based on analytics alone, but we need to communicate with our API consumers one-on-one and build an active community.
Summary and Discussion
Many approaches to proper API design and development have been proposed and these approaches are subject to passionate debates. However, there is no wrong or right design approach, but there is an approach that fits into a specific company culture better than others.
This is why we propose that you pick and choose the phases or steps from this design and development approach that really fit your company culture. This is one of the best ways to make sure that the API design and development approach is actually adopted and lived by the team.