Today, the best practice when implementing APIs on a large scale is to start with an API design stage. This approach is called API design-first, sometimes also known as API-first, schema-first, or design-first.
The design-first approach advocates for designing the API’s contract first before writing any code. This is a relatively new approach, but is quickly catching on, especially with the use of API description formats.
There are several tools that allows you to use the design first approach, one of them is ApiBldr that allows designing the API in a visual and friendly way.
What about Code-first approach?
The code-first approach is a more traditional approach to building APIs, with the development of code happening after the business requirements are laid out, eventually generating the documentation from the code.
Like any product, the concept of the API starts with the business team identifying an opportunity. The opportunity is analyzed and a plan to capitalize on it is created in a text document by strategists, analysts and other business folks. This document is then passed along to the development teams like front-end developers, testers and other R&D team members, which is where the plan is being coded into the API.
Design-first vs Code-first
Design-First: The plan is converted to a human and machine-readable contract, such as an OpenAPI document, from which the code is built as a skeleton and the API definitions are shared accross the R&D teams to begin working in parallel (using mocks).
Code-First: Based on the business plan, API is directly coded. Only at a later stage, an API document can be generated and published. Here the R&D teams are waiting for an initial release of the API to be ready before starting to test it and integrate into client side code.
What is OpenAPI Specification?
OpenAPI is a description of HTTP-based APIs which are typically, RESTful APIs. It comes in the form of a YAML file or definition, that describes the inputs and outputs of an API. It can also include information such as where the API is hosted, what authorization is required to access it, and other details needed for consumers and producers (such as web-developers).
Definitions can be written by hand, by tools, or even generated from code. Once an API has been written down, we say it has been described. Once API has been described into a definition, it becomes a platform for tools and humans to make use of. A typical example of making use of API definitions is to generate human readable documentation from it.
Describing APIs into an OpenAPI definition allows you to leverage tools to help automate a lot of API related processes.
For better understanding and supporting your design-first approach, you can use SaaS products like RestCase, which allows you to build your API definitions using a visual designer, generate great documentation which can be easily changed to your feel & look, API quality and security insights for the design phase and more...
OpenAPI Specification Benefits
OpenAPI is useful for consumers, developers (also called producers) and API designers. Each can benefit from knowing and utilizing tools that consume OpenAPI definitions.
Consumers of the API
If you’re required to consume some API you may need an SDK, and if you have OpenAPI you could generate SDKs for many different languages. The benefit is in having familiarity with a single type of SDK or even customizing the SDK to suit your needs. Each and every API described with OpenAPI can then be turned into an SDK of your choosing.
API Developers (Producers)
Building APIs can be quite fun, particularly when you have a contract to develop against. Building out the boilerplate of an HTTP server is less fun once you’ve done it many times. Generating boilerplate code and stubs from an OpenAPI definition gives you speed and consistency (since you can customize the templates to your needs).
Although there are even more exciting methods of developing APIs, using OpenAPI definitions during runtime to act as a router (have API operations map to classes/methods in code) and as a validation layer (incoming requests will fail validation unless they conform to the OpenAPI definition’s schema). Such practices are becoming more common in microservice-oriented architecture where services are being built-out at a faster rate.
API Designers
Designing APIs has also been given a new focus recently and its importance cannot be understated. APIs should be designed with longevity in mind as changing them, means changing the contract for the consumers and maintaining API versioning. No-one likes getting stuck maintaining an old API!
OpenAPI is a medium to communicate to both consumers and producers, allowing designers to get feedback early in the process and to iterate based on that feedback.
Design becomes even more interesting when it comes to managing more than one API. In those cases, consistency also plays an important role.
Standardizing all your APIs to have consistent patterns becomes possible when you can measure those patterns.
Leveraging OpenAPI for Design-first approach
The OpenAPI definitions, that are described by tools or by extracting annotations from code. They are then transformed into API documentation, server stubs / routers and client SDKs. There are certainly more work flows that could be diagrammed out, ones that provide more specific value depending on the business cases.
Example Workflows:
- Generating API documentation
- Automating parts of testing (APIs)
- Getting early feedback on the design of the API
- Ensuring API consistency especially if you have several API's
- Comparing API changes across versions
Practicing API Design
Today, many companies realized that the API world is basically a universe and changed their way of work accordingly.
Dedicated API architects write a specification and all the stakeholders, from developers to product managers and external consumers, are involved in the process.
APIs became products, so they need to consider not only the technical but also the business and legal concerns. In smaller companies, or when APIs are developed for internal use only, it is the frontend developers who should put on the API designer’s hat. They are the ones who eventually consume the API and therefore should have the best understanding of the requirements.
In any case, the specification should be shared and visible always to the different stakeholders through documentation or the source (json or yaml files).
When the specification is complete, you can then generate mocks and documentation. Thanks to this, frontend and backend development can happen independently, without teams waiting for each other. Backend engineers write the API server to specification and test it, or even leverage tools capable of generating server-side code stubs from OpenAPI to save time writing code. Simultaneously, the frontend developers can build their application and receive correct API responses from the mock server.
Feedbacks
One of the most important aspects of Design-first approach is the ability to get feedbacks very fast through:
Documentation (public, private)
There are many tools that supports automatic documentation for OpenAPI definitions. Sharing this documentation with all possible stakeholders like different R&D team members and perhaps even early API adapters clients can lead to many great inputs and thoughts since each stakeholder has a different view and probably represents different audiences for your API.
Testing
Since the API definitions are a contract, it can be tested even before the implementation of the business logic is done. When the tester is looking at the different models, paths and other aspects of the API, his input can be very valuable, especially at the design phase.
Server \ Client Code
When you generate a server-side code stub based on the OpenAPI definition, the developer or developers who are starting to implement the business logic can find issues at the programming phase and update the API definitions accordingly.
Summary
Design-first approach takes place before or in the early stage of the API development, and the initial output of this approach is a human and a machine-readable definition of the API. You cannot leverage the power of OpenAPI for these stages of the API lifecycle if the specification is an output of your code instead of an input.
You could still argue that you can build a proper API lifecycle without a specification, and you only need OpenAPI to produce documentation. After all, there are enough successful software companies that do not practice test-driven or contract-first development. However, doing so would leave at least half of what OpenAPI can do on the table. It is important to consider that OpenAPI is so much more today — a vast and robust framework for the whole API lifecycle and starting with the design-first approach can boost not only your development time and feedback, but also to create an engagement of your API users and stakeholders.