Recently, Microsoft engineers officially unveiled TypeSpec, a new language tailored for API-centric development that addresses the complex needs of modern API design. TypeSpec is an open-source, extensible language inspired by TypeScript and C#. It supports various protocols and serialization formats, enabling developers to use a single tool to manage multiple API specifications.
TypeSpec describes APIs using supported protocols or serialization formats with concise syntax and editor tooling for Visual Studio and VS Code. Using TypeSpec, developers can encapsulate common data types, API patterns, and API guidelines into high-level, reusable components they can share across teams or ecosystems.
An example of a TypeSpec spec and the resulting OpenAPI schema side-by-side (Source)
Once developers define the specification, they can compile it to standards-compliant OpenAPI, JSON Schema, Protobuf or all three simultaneously.
The language is highly extensible, supporting custom decorator vocabularies and type templates that enable developers to tailor APIs to specific business or application logic domains. TypeSpec also promotes ecosystem development by allowing the creation and distribution of packages via NPM, which can be utilized within organizational boundaries or shared across the broader developer community.
TypeSpec is actively used within Microsoft, especially by the Azure services and Microsoft Graph teams. By using TypeSpec in their development processes, Microsoft engineers increase the reliability and efficiency of TypeSpec for API development in other real-world scenarios.
Brian Terlson, principal software architect, Azure Developer Experience at Microsoft, is the architect for TypeSpec and the Azure SDK for JavaScript. He has worked on TypeSpec since its beginning in 2019. Terlson says, "As we've been iterating and improving on TypeSpec, we think now is the right time to get more feedback from the broader API development community." He notes that the TypeSpec team is "eager to get more feedback to understand better what we should prioritize as we work towards a 1.0 release."
InfoQ spoke with Terlson about TypeSpec, its value proposition, and how it compares to other type definition languages.
InfoQ: Why invent a new language when multiple Interface Description Languages (IDLs) already exist? What is TypeSpec's primary innovation?
Brian Terlson: TypeSpec originated from our experience delivering services at a massive scale in Azure. At that scale, with many services and teams, we needed a solution to help developers quickly create consistent and high-quality APIs.
TypeSpec is unique in several ways. First, we focus heavily on enabling API abstraction so API designers can build libraries of reusable API components. This matters when working at scale, and we rely extensively on this within Azure to reduce the development cost, review cost, and complexity in service specifications while improving API quality and consistency.
TypeSpec is also protocol agnostic, supporting particular protocols or serialization formats added in with libraries. This allows TypeSpec to serve as the single source of truth for more than just a single protocol, which is especially valuable as developers and applications are increasingly polyglot and involve implementations across multiple languages and protocols.
Finally, developer familiarity: TypeSpec also takes inspiration from existing languages, mostly TypeScript, but also C#, so our language should feel familiar to many developers. We also use JavaScript for our extensibility and packaging story, which brings a lot of power without building something new that developers must learn.
InfoQ: What is the fundamental value proposition that TypeSpec provides to software architects?
Terlson: TypeSpec aims to make building and working with APIs less costly and more practical. By building your API first, you unlock many significant advantages in terms of scalability and API quality.
API-first approaches improve scalability by enabling code generation across vast swaths of your application stack and shifting review and governance duties earlier in the process, where changes are less costly.
Also, its ability to abstract common API shapes into reusable components effectively aligns the developer's interest in doing the simplest thing with the architect's interest in doing the correct thing. You use the component in both cases, and the right thing happens.
TypeSpec is also committed to interoperability with API description formats like OpenAPI, so you can get these benefits all while interoperating with your existing toolchain.
InfoQ: What's your vision for TypeSpec for the next few years?
Terlson: Right now, we're working toward building out all the capabilities we want the community to give us feedback on before we stabilize for 1.0, including moving Azure SDK's code generation technology into the TypeSpec project.
We're very proud of this tech and excited for folks to start generating clients and servers for their APIs.
You'll see us continue to build out the language, such as adding the ability to define specific values and use those values to define things like API examples. We're also adding new library features, such as defining streaming and event APIs to support protocols like server-sent events and streaming JSONL.
In the long term, our work depends heavily on the feedback we hear from the community. We're interested in adding more capabilities to the language to describe new kinds of APIs, expanding our standard library to support new protocols, serialization formats, and standard data shapes, and innovating on code generation so it can be used in more places across the software ecosystem.
So, I encourage everyone to head over to our GitHub and let us know what you think!