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. A regression, rather than progress, if you ask me.
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.
