Improve API adoption with the OpenAPI Specification
Length:
8 min
Published:
December 8, 2022
At DX Heroes we work on developer experience, both for our own developers and for our clients. As more companies build on APIs, we work with APIs more. We design their structure, improve their data models, and polish the documentation. After enough projects, one pattern kept coming back. A company decides to adopt a documentation standard to make its API easier to read or reuse, but it does not put in enough work to do it right. The result is a document that no longer matches the real API, which makes the developer experience worse, not better. That pattern is why I wrote this article. It sums up the benefits and the challenges of using an OpenAPI Specification, or any other format that describes an API.
What is the OpenAPI Specification?
The OpenAPI Specification is the most common standard for documenting, visualizing, and consuming REST APIs. Technically it is a YAML or JSON file with a defined structure. It started as Swagger and was donated to the Linux Foundation in 2015. Today it is an open-source project maintained by the OpenAPI Initiative, a consortium of experts who create, evolve, and promote a vendor-neutral API description format [1]. Over the years, a lot of API tooling started taking OpenAPI documents as input. You can now feed an OpenAPI document into tools that generate client or server code, test APIs, mock them, and even check for security vulnerabilities. The full list lives on the OpenAPI page [2]. An OpenAPI document lets you do a lot of useful things, yet many companies have no specification at all, or one that no longer matches their API.
Why OpenAPI matters for you
A good OpenAPI specification makes life easier for the people who build the API and for the people who consume it. Here is a small fraction of what it gives you:
- API developers and business stakeholders can iterate on the API design together, think through data structures, and plan new features.
- API developers can pair OpenAPI with tooling to test and validate the actual implementation.
- OpenAPI lets you build developer portals for your API, which helps consumers.
- Consumers can read an OpenAPI document to quickly understand how the API works and guide themselves through the integration.
- You can mock a real API from an OpenAPI document, so consumers focus on business logic instead of waiting for the real implementation. This helps larger partner companies shorten their time to MVP.
The biggest benefit is probably code generation. From an OpenAPI document you can generate client code in almost any language and make your API far easier to use. If your API is also your product, that code generation can give you a real edge over competitors. But creating and maintaining a good OpenAPI specification is not easy.
How to create OpenAPI and keep it alive
Creating and maintaining a good OpenAPI document comes down to discipline and to close work between business and development. There are three broad ways to design an API and its OpenAPI document: design-first, code-first, and writing the document by hand afterwards. I will skip the manual approach, because I do not think it leads to sustainable API development.
Design-first
In the design-first approach, you create or change the OpenAPI document before you write any API code. The document is the single source of truth, and the resulting API is validated against it. When developers or the business decide the API needs to change, for example a new feature, they first propose the change in the OpenAPI document. Every stakeholder, business and developer, gets a chance to think through the change and its impact. You can also discuss proposed changes with trusted consumers, and you can even generate a mock API so they can try the new version. Only after the proposal is approved does the API code change or get implemented. According to Postman [3], this approach keeps growing in popularity.
Code-first
In the code-first approach, the API code already exists and developers add tooling that generates the OpenAPI Specification from annotations in the code. This needs less involvement from the business. The catch is that developers sometimes forget to update the annotations when they change the code. That leads to a mismatch between the OpenAPI Specification and the API, which can be a serious problem.
@ApiBearerAuth()
@ApiTags('cats')
@Controller('cats')
export class CatsController {
constructor(private readonly catsService: CatsService) {}
@Post()
@ApiOperation({ summary: 'Create cat' })
@ApiResponse({ status: 403, description: 'Forbidden.' })
async create(@Body() createCatDto: CreateCatDto): Promise<Cat> {
return this.catsService.create(createCatDto);
}
@Get(':id')
@ApiResponse({
status: 200,
description: 'The found record',
type: Cat,
})
findOne(@Param('id') id: string): Cat {
return this.catsService.findOne(+id);
}
}
The challenges
Each approach has its own set of challenges, and either way developers need time. They need time to design the API so it can absorb small changes without shipping breaking ones by accident. They need time to set up solid end-to-end tests that confirm the API behaves as expected, and to automate as much as possible so human error has fewer chances to creep in.
In design-first, the challenges are mostly about communication between business and development. The business team has to take part in the design, which can be slow and a bit more technical than they are used to. Sometimes the business, or even the developers, do not see the point of an OpenAPI document and refuse to take part. When that happens, spell out the benefits for each specific role. Knowledge is another hurdle: developers need a good grasp of API design to work with the document, so this is usually not a job for juniors. Then there is keeping the document and the real API in sync. It is a smaller problem here than in code-first, but it still pays to run regular checks that validate the API against the document. You can trigger those checks on commits to your main branch in a CI/CD pipeline.
In code-first, the challenges lean toward development, and the biggest one is keeping the document and the real API in sync. Development teams need solid conventions for API changes, careful reviews of every PR that touches the API or the specification, and good end-to-end test coverage to catch breaking changes and any mismatch. A less technical challenge is again the communication between business and development. When it breaks down, you end up with an API that does not really do what the business needs, or with layers of abstraction that hide what the API is even for.
Conclusion
A good OpenAPI specification can greatly improve the experience for both API developers and consumers, and used well it gives you an edge over competitors. That edge has a cost. You have to keep business and development talking, and you have to give developers enough time to set up the technical processes that produce a quality API matching the document. I hope this article gave you some insight into the challenges of documenting an API and helped you spot the weak points that lead to trouble. If you are about to design an API or you are wrestling with API documentation, reach out to us. This is our daily bread.
Sources
You might also be interested in:
Want to stay one step ahead?
Don't miss our best insights. No spam, just practical analyses, invitations to exclusive events, and podcast summaries delivered straight to your inbox.