OpenAPI Is Not Enough
There are things you simply can't do with OpenAPI.
I used to think OpenAPI was the best way to define REST APIs. And I bet you think that way, too. After all, OpenAPI has so many benefits that it's easy to ignore its drawbacks—until you feel them, that is. Yes, OpenAPI gives you the ability to, among other things, document your API, mock it, test it, govern it, expose it, and translate it into code. However, there are situations where what it does isn't enough, as I'll show you next. In those cases, there are better alternatives that can give you what OpenAPI can't. Keep reading to learn more.
This article is brought to you with the help of our supporter: Speakeasy.
Further expanding its best-in-class API tooling, Speakeasy now empowers teams with open standards. The platform simplifies OpenAPI Overlay adoption so you can focus on building. Click the button below to check out the playground.
OpenAPI is a fantastic tool. It's been used to fuel the growth of REST API usage both internally within organizations and also publicly. It's easy to use by both humans and machines as it accepts YAML and JSON formats interchangeably. There are numerous tools and applications—both free and commercial—you can use to manipulate OpenAPI in countless ways. As well as editors, techniques, and frameworks, that help you handle, manage, share, and do anything you need. OpenAPI documents are seen as the source of truth of API definition, the starting point for everything API related. The summary is that there's a whole industry that's been built around OpenAPI. And people like it like this. That's why, when you ask someone how they mitigate some of OpenAPI's limitations, they look at you incredulously. "Limitations? What limitations?"
Yes, OpenAPI has limitations. There, I've said it. You can hate me now. One limitation has to do with the ability to use OpenAPI to generate high-quality code for sophisticated APIs. OpenAPI uses JSON Schema as its validation engine. Since JSON Schema doesn't define what attributes you can have on your JSON document (it only checks if the ones you use are correct according to the schema), you can use anything unless explicitly disallowed. This makes it difficult to properly define data types that, by nature, need to be strict in certain programming languages, such as Java. So, for example, translating things like JSON Schemas' oneOf into code isn't practical. I'm not the only one saying it. Quentin Pradet, a Senior Performance Engineer at Elastic, shares that "It is hard to go from a collection of oneOf and anyOf to actual request and response types in a given programming language. It works well enough for simple cases, so many projects still try it."
Elasticsearch's API specification is all written in TypeScript. They used it as the source of truth instead of OpenAPI precisely because of the limitation I mentioned above and other smaller ones, the team opted for using TypeScript, a strongly typed language, to define their REST API. They still have an OpenAPI document. However, it's generated from the specification written in TypeScript. Sylvain Wallez, a Principal Software Engineer at Elastic, adds that "JSON schema doesn't model data structures, but expresses constraints they must verify." Wallez sees OpenAPI as a viable format for generating an API reference, but not so much for code. While Elastic's approach feels like a stretch, there are other companies following a similar path.
Microsoft is one company that's betting on using something other than OpenAPI as the source of truth for API definition. In fact, they've been working on it since 2020. I'm talking about TypeSpec, which, according to the documentation, is "a language for defining cloud service APIs and shapes." One of the use cases they promote is called "Write TypeSpec, emit OpenAPI." Does that sound familiar? It's similar to what Pradet and Wallez from Elastic are doing. Microsoft claims that TypeSpec can help developers define an API in a familiar way because it looks like TypeScript. Other advantages include full VS Code support, including syntax highlighting and code completion, and the ability to generate different types of assets, including code, docs, and even an OpenAPI description.
Another company that's been following a similar approach is Amazon. They started working on their API definition language one year before Microsoft. They claim that Smithy—that's the name of their API definition language—"provides an intuitive syntax that codifies best practices learned from years of experience building services and SDKs in over a dozen programming languages." What's not to like about it? The benefits are quite similar to what Microsoft offers. With the flavor of AWS, though. And, if there's one thing they're good at, it's building an ecosystem. They have a repository of tools that work with Smithy and promote things like client and server code generators, learning resources, IDE plugins, and even tools that convert between Smithy and other standards. The works.
I wonder if there are other companies doing similar things. OpenAPI itself should fix those limitations before other players increase the already growing fragmentation of API definition languages. After all, one of the benefits of having strong standards is interoperability.