API Design in the Post-OpenAPI Era

New description languages and frameworks are slowly changing how APIs are designed. This doesn’t mean the industry-standard OpenAPI Specification becomes obsolete — instead, it will likely become more of a compilation target for new description languages and frameworks, like TypeSpec. Hopefully, the result will be reduced errors and a better API development experience.

Daniel Kocot, Head of API Consulting, codecentric AG, will return to speak at Platform Summit 2024.

This year’s Platform Summit will bring together a handful of experts in areas like OpenAPI Specification, TypeSpec, API design, and beyond. For instance, Daniel Kocot, Head of API Consulting, codecentric AG will discuss navigating the “post-OpenAPI” era using innovative design frameworks.

I recently caught up with Kocot, who spoke at Platform Summit in ’19 and ’23, to explore the undercurrents surrounding these new design trends a bit more deeply. Check out the interview below to learn how new tools and frameworks will help deliver on the promise of API-first. Also, be sure to attend Platform Summit 2024 for plenty of helpful knowledge to inform your internal API development processes.

What are some recent trends you’re noticing in the world of API development?

A very nice question to start with. Currently, I can see two trends in API development. The first thing I see is that the APIOps movement, which I have been a part of since the beginning, is becoming more and more important. More specifically, I clearly see a burgeoning of domain-specific languages (DSLs) to programmatically create API descriptions. This is very valuable in turning good data products into good API products, as the programmatic creation of the interface ensures consistency between the API and the underlying data product. I would even state that DSLs/programmatic creation of the interface is the only way to turn good-quality data products into good-quality API products.

The second trend I see is that API development is increasingly being seen as part of software engineering. The use of the programmatic approach based on a DSL and APIOps fits in with this. Both trends are changes in the mindset from which practical technology is derived.

You say we’re entering a post-OpenAPI era. Why is this, and how do you anticipate it will affect API design going forward?

We can clearly see that a large number of APIs are created through the use of code first. From a developer’s point of view, this is the easiest and perhaps most painless way to quickly design an interface. However, the design of an API should not be about speed but about ensuring long-term availability until sunsetting. A standard for a description such as OpenAPI, AsyncAPI, JSON Schema, and ProtoBuf quickly degenerates into an unwelcome companion whose added value is not visible.

If we now look in the direction of frameworks or tools such as TypeSpec, TaxiLang, Fern, and Apple Pkl, we are not simply creating or writing a textual file based on traditional development virtues, which are only used for reading purposes without the corresponding tooling. Instead, we are moving programmatically from the model description to the interface description. And this is exactly what describes the post-OpenAPI era for me.

What, then, do you think will be the role of OpenAPI Specification in this new era? How might the standard evolve?

In this post-OpenAPI era, I see standards like OpenAPI as automatically generated artifacts. Nothing more. Let’s be honest: nobody should really create or edit OpenAPI, JSON schema, and other files directly. The reason is that the error rate is very high despite linting and validation in today’s IDEs. But there is no question in my mind that the standards need to evolve.

You mentioned a few frameworks that go beyond the status quo to improve the developer experience. Which one are you most interested in, and how do you think it will be used?

I currently have a strong interest in TypeSpec, as this type of description is considered to be the most advanced, and its clear priority is to describe the interface. Despite its maturity, there will certainly be one or two breaking changes at some point. I see TypeSpec as a key tool in automation, allowing us to secure interfaces more effectively from the start through consistent governance.

In the past, you’ve spoken about the reality of API-first. Do you think these new tools help deliver on the promise of design-first, code-first, or entirely enable new development processes?

The tools and frameworks will provide even better support in achieving API-first, which is just the strategic approach to make APIs one part of the business of an organization. Whereas design-first and code-first refer to methodologies for creating APIs. A preferred multi-stage process implements API design first using API thinking: It starts with thinking in APIs, then moves on to designing the interface using a DSL such as TypeSpec, and ultimately leads to a high-quality implementation of the backend that also fits the description.

Without giving away too many details, what can attendees expect from your upcoming talk at the Platform Summit 2024?

The talk will focus on the possible integration of frameworks into existing development processes. Through this, we will take a first look at a possible future of API development.

Are you excited for the Platform Summit? Why or why not?

Again, I’m very excited about the Platform Summit this year. After 2019 and last year, I’m looking forward to being also a speaker this year. I like that the Platform Summit is a well-curated and well-organized event.