‍Improve API adoption with Open API Specification

Our work at DX Heroes mainly focuses on improving developer experience for both our and our clients developers. As more and more companies use APIs we also work with APIs more. We design API structures, improve their data models and polish the documentation. After working with enough APIs I started to see a recurring situation: Some companies decide to use documentation standards to improve the documentation or reusability of their API. However, they don’t allocate enough resources to do it right and the outcome is a document that doesn't match the real API, actually making developer experience worse. This pattern motivated me to write an article which sums up the benefits and challenges of using an OpenAPI Specification (or other formats used to describe an API).

What is OpenAPI Specification

OpenAPI Specification is the most common standard for documenting, visualizing and consuming REST based APIs, technically it is a YAML or JSON file with a specific structure. It was first introduced as Swagger and in 2015 was donated to the Linux Foundation. Now it is an open source project maintained by the OpenApi initiative which is a consortium of experts that are focused on creating, evolving and promoting a vendor neutral API description format [1]. Over the years a lot of tooling in the API field started using OpenApi documents as an input. Currently, you can use OpenApi documents as input in tools that can generate client or server-side code, test APIs, mock them and even validate for security vulnerabilities. Full list of tools can be found at the OpenApi page [2]. You can use an OpenApi document to do a lot of useful things, however a lot of companies don't have any OpenApi specification or their OpenApi specification does not match their API.

Why is OpenAPI important for you

Good quality OpenApi specification for your API can simplify work for both the developers and consumers. Here is a list of only a fraction of potential benefits of OpenApi Specification:

• API developers, together with business stakeholders can use OpenApi Specification to iterate on API design, think about data structures, and plan new features.
• API developers can use Open Api with tolling to test and validate actual implementation.
• OpenApi also enables developers to create developer portals for your API which helps the consumer.
• Consumers can use easy to read OpenApi documents to quickly understand inner workings of the API and guide them through integration.
• OpenApi documents can be used to mock real APIs so consumers can focus on business logic instead of waiting for the real implementation. This is especially useful for bigger partner companies that want to shorten their time to MVP.

Probably the biggest benefit of OpenApi Specification is code generation. OpenApi documents can be used to generate client code in almost any language and drastically simplify the use of your API. So if your API is also your product, code generation from OpenApi can give you a huge advantage over your competitors. However, creating and maintaining a good quality OpenApi Specification is not easy.

How to get OpenAPI and maintain it

Key to creating and maintaining a good Open Api document is discipline and collaboration between business and development. There are generally three approaches to API and OpenApi Specification document design: design-first, code-first and manually creating it afterwards. I won’t talk about manual writing of OpenApi Specification as I don’t believe that it is a good approach to sustainable API development.

Design-first approach

First, let’s take a look at the design-first approach. With this approach the OpenApi Specification document is created or changed before any actual API code. Open Api specification document is used as a single source of truth and the resulting API is validated to match specification. When developers or businesses decide that the API needs to be changed (eg. new feature) they first propose change in the OpenApi document. Every API stakeholder (business, developer) has a chance to think about the proposed change and its impact. You can also discuss proposed API changes with some of your trusted consumers - you can even generate a mock API for them to try a new version. Only when this proposal is approved can the code of the API be changed or implemented. According to Postman [2] the popularity of this approach is steadily growing.

Code-first approach

Another approach is code-first where code of the API already exists and developers add tooling that generates the OpenApi Specification based on annotations in code. This approach requires lesser involvement from business. However, sometimes developers can forget to update annotations when updating code. This can lead to a mismatch between the OpenApi Specification and the API which can be a major issue.  

@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);
  }
}

Challenges

Each approach has its own set of challenges but either way developers always need time. They need time to design an API in a robust way that can handle small changes without accidentally releasing breaking changes. They need time to set up robust end-to-end tests to ensure that the API is working as expected, automating as much as possible to minimize any chances of human error.

Challenges in design-first are mainly tied to communication between business and development teams. Business team must participate in the design of an API which might be time consuming and perhaps a bit more technical. In addition to that, sometimes business or even developers might not fully understand the benefits of having an OpenApi document and refuse to participate in the API development. In this case it is important to clearly communicate the benefits for each specific role. Another challenge might be knowledge, developers need to have good knowledge of API design to be able to work with the OpenApi document, so this is most likely not a task for junior developers. Then there's keeping the OpenApi document and the real API in sync - Even-though this isn’t as big a problem as in code-first it is still a good idea to have regular checks validating your API with the OpenApi document. These checks can be triggered by commits to your main branch in a CI/CD pipeline.

Challenges in code-first are more development focused and the biggest one is keeping the OpenApi document and real API in sync. Development teams have to build very solid conventions for API changes, perform thorough reviews for PRs that introduce changes to the API and/or OpenApi Specification and have good coverage of end-to-end tests to discover breaking changes in an API and any potential mismatch. Another, less technical challenge, can be the communication between business and development during API development. Lack of communication can lead to an API not really fulfilling a function defined by business or having levels of abstraction that make it hard to understand what the purpose of the API truly is.

Conclusion

OpenApi Specification can highly improve developer experience of API developers and consumers and when used right it can provide an advantage over your competitors. However, this advantage has its cost, as you have to support communication between business and development, and provide developers with enough time to set up technical processes necessary to provide a good quality API that matches the OpenApi document. I hope that this article gave you some insight into challenges around documenting an APD and helped you to identify weak spots that might lead to any potential issues. If you are thinking about designing an API or struggling with API documentation feel free to reach out to us - all of this is our daily bread!

Sources

[1] https://www.openapis.org/about

[2] https://openapi.tools/

[3] https://www.postman.com/state-of-api/api-first-strategies/#api-first-strategies

You might also be interested in:

When Speed Matters: Why Investment into Faster Integrations Pays Off in the Long Run