30. 10. 2024 Oscar Zambotti Automation, Development, Documentation

The OpenAPI Tales: A New Dawn

When we talk about APIs, we developers are generally biased, and focus on how they’re implemented technically – how they work, how they integrate into larger systems – and we settle for that. But there’s a valuable part of API development that often gets overlooked: creating their descriptions.

This practice tends to be undervalued, so it’s procrastinated or even ignored, but it’s very important for many aspects. An API description is more than just a static document. It’s a blueprint for the future of a project. It can help you streamline existing processes, improve collaboration, and unlock new possibilities for innovation.

We can achieve our goal using API description languages. Assuming that we know what an API is and that we know that it’s based on HTTP semantics and RESTful principles, here are the things we want to describe about an API:

URL (or endpoint)
HTTP method
Parameters: HTTP headers, query parameter, request body
Expected HTTP response codes
Expected response headers
Response body

The API description languages provide details about the structure of an API, highlights these properties and even others – like the security aspects – all encoded in a format such as JSON or YAML. The benefits of this approach are:

A common form of communication between API providers and API consumers
A document that can offer to a developer a “human readable” way to understand how an API works, combined with explanations that clarify how it operates, perhaps with enriched formatted descriptions
A specification that provides a “machine readable” format for software tools
Avoiding a source code release, so no implementation details are disclosed, if this is required by the organization
Not tied to a specific programming language
Allowing for a vendor-neutral approach

The most widely used API description language is OpenAPI. The basis of the OpenAPI Specification is Swagger, donated in 2015 by SmartBear – which used it for their products and open source tools – to the OpenAPI Initiative (OAI), which has an open governance structure under the Linux Foundation.

The OpenAPI community is constantly evolving, with Special Interest Groups (SIGs) driving innovation: by focusing on specific niches, these groups help shape the future of API development and documentation.

In addition, one of the most appreciable features of OpenAPI is a standardized pattern for extending the OpenAPI specification, so for example vendors may introduce non-standard configuration parameters to tailor their tools to specific requirements.

As the goal of this blog post is not to explain the OpenAPI Specification at the technical level, I suggest signing up for the free official OpenAPI Fundamentals training course by the Linux Foundation.

What-first?

At what point during the software development cycle is it best to create an API description? This question doesn’t have a clear answer, it depends. But let me describe two approaches: design-first and code-first.

The design-first way is better for prototyping and shaping ideas. If the project’s code hasn’t begun to be implemented yet, there’s a chance to write an API description starting from the analysis: defining the models, involving figures who are not strictly technical, and letting other stakeholders participate. It’s possible to use a simple text editor or one of the many graphical tools that can help visualize the structure of the APIs, helping us with the design.

The code-first approach is often the most practical choice, especially for existing projects with established APIs. In this scenario, you can leverage a variety of libraries and tools tailored to your programming language to automatically generate OpenAPI descriptions from your existing codebase. By annotating your code with specific metadata, you can provide the necessary information to create an accurate and up-to-date API description. This streamlined process ensures that your API documentation remains synchronized with your codebase, reducing the risk of inconsistencies and errors.

What now?

So, after all the effort, we’ve forged a powerful tool: our API description. But the journey isn’t over. In future posts, we’ll deploy it to craft clear API documentation and automate the generation of code, both frontend and backend. With this instrument in hand, we’re poised to significantly enhance any project.

These Solutions are Engineered by Humans

Did you find this article interesting? Does it match your skill set? Programming is at the heart of how we develop customized solutions. In fact, we’re currently hiring for roles just like this and others here at Würth Phoenix.

Oscar Zambotti

Software Engineer in the R&D Team of the IT System & Service Management Solutions group, Würth Phoenix. Some people say that I do nothing but press buttons. It's true, but I know how to do it in the right order. Random trivia: from Trentino (Italy), in love with everything is technology, gamer, TV shows enthusiast, former radio speaker and club DJ and entertainer, AC Milan supporter, but most of all father and husband.