TypeSpec reminds us why OpenAPI exists in the first place

I’ve recently found out about TypeSpec, a new language aimed at describing web APIs, through an interview that bears the provocative title of API Design in the Post-OpenAPI Era. Leaving aside the fact that OpenAPI is very much alive, what left me stupefied was the assertion that OpenAPI files should be “automatically generated artifacts and nothing more”. After digging a bit, I found the picture to be slightly more reassuring, but still quite representative of a world that keeps steering away from human-driven design to bury itself in curly brackets paradises.

OpenAPI is not perfect and it doesn’t matter

OpenAPI specification files (OAS) are artifacts whose existence rests on the assertion that API design is a complex endeavor that requires collaboration, discussion, and a single source of truth. OpenAPI is agnostic as to the actual implementation because APIs are interfaces meant to be used by humans and machines alike. As I explained in How to assist API design as a technical writer, APIs are made of words that have to be chosen carefully and woven into structures that make sense for all users. The greatness of OpenAPI is that it enables all actors to participate on equal ground to API design.

Many developers hold a grudge towards OpenAPI and API first design for reasons that are sometimes hard to untangle. It’s true that OpenAPI has limitations, and that it makes it difficult to account for certain API behaviors such as conditional schemas. It’s also true that code generation from OAS still isn’t that great, although one might argue that it’s not really the goal of a design tool to provide robust code implementations – would you ask Figma to generate perfect code in your framework of choice? I guess a certain type of web developers would, but that’s misunderstanding what the tool is for.

In the case of TypeSpec, developers get a TypeScript inspired language that lets them describe, lint, and generate APIs without having to meddle with the dreaded YAML of OpenAPI files and the apparently arbitrary decisions around it. The pros from a coder perspective are manifold and range from more accurate data types to IDE support to easier patterns. What about the design and documentation side, though? The current documentation decorators are incredibly limited compared to OpenAPI, and even though TypeSpec is still evolving, I’m not really sure folks will turn documentation into a high priority item.

Design is hard because it’s a human problem

Darrel Miller, a principal API architect at Microsoft, explained:

We can have the opportunity to hugely improve the OpenAPI specification if we stop trying to meet the needs of description authors that can be addressed by TypeSpec. For so long we have been trying to meet the needs of both humans and tools with the same artifact and it is spectacularly hard.

I agree that meeting the needs of both humans and tools is a spectacularly hard mission. But so are design, documentation, usability, and other fields that bridge the gap between humans and software. And while I sincerely hope that TypeSpec will triumph and extend to the point that it’ll ease the creation and editing of OAS while maintaining decent docs support, a part of me thinks it’s yet another attempt at circumventing the complexities of human behavior and the sociology of software development through a secret idiom that caters to developer sensibilities.

One does not simply give up on human-computer interaction by taking a step back and hoping that’ll allow us to take three leaps forward.

I don’t want to be too harsh upfront, especially given how young TypeSpec is, but as of now it looks more like an invitation for developers to define APIs somewhere else that isn’t YAML, in a place that could be a shared design ground for all, but whose status as a collaborative space is nebulous at best. None of what TypeSpec brings to the table solves the fundamental problem of opening API design to more people. If anything, it seems a way of wrestling back control of API development from other collectives. I hope to be proven wrong.

“It’s the developer experience, stupid!”

While I was thinking about the nascence of TypeSpec, it occurred to me that what’s happening in the API design space is similar to what happens in other spaces where the needs of human-driven design and development productivity encroach. Think of all the attempts at extending Markdown, stowing away the need for a consistent model of documentation (hello, DITA, my old friend). Simpler grammars and systems, subsets of subsets of human language, all nod to the presumed impatience of software developers. I say presumed because it’s not clear to me that developers would give up precision and collaboration for minor IDE comforts.

Software design seems to go through recurrent phases dominated by complexity and completeness followed by phases made of simplicity and limitations. With almost no memory of previous cycles, developers are doomed to reinvent the wheel and discard previous innovations, dragging design and tech-comms disciplines with them. Here’s, perhaps, where humanism in tech can find its noblest purpose: in providing a beacon of necessity that trends won’t dislodge.

As we navigate the ever-evolving landscape of API design, it’s crucial that we don’t lose sight of the bigger picture. Although tools like TypeSpec offer enticing promises of simplified development and improved developer experience, we must approach them with a critical eye. The allure of code-like constructs should not come at the cost of collaborative, human-centered design principles. OpenAPI, for all its complexities, has made significant strides in democratizing API design and fostering cross-functional collaboration. Let’s not sacrifice all that on the altar of curly braces.