Microsoft's Journey to a Powerful API Definition Language
CIO Review Europe | Sunday, June 09, 2024
Microsoft introduces TypeSpec, an API definition language and platform for developers, architects, and managers in complex environments. It offers concise syntax, editor tooling, interoperability, productivity enhancement, and extensibility.
FREMONT, CA: Microsoft recently introduced TypeSpec, a new API definition language and platform designed to meet the evolving needs of API developers, architects, and managers in an increasingly complex environment.
TypeSpec, as its name suggests, is related to TypeScript, the Microsoft-developed superset of JavaScript. Inspired by two languages designed by Microsoft language expert Anders Hejlsberg—TypeScript and C#—TypeSpec follows the open-source model of TypeScript.
Stay ahead of the industry with exclusive feature stories on the top companies, expert insights and the latest news delivered straight to your inbox. Subscribe today.
TypeScript inspired most syntax and type system semantics and is great at describing JSON data shapes. From C#, the notion of namespaces was inherited, and how they merge across files was a natural fit for an API description language.
TypeSpec enables the description of APIs using any protocol or serialisation format with concise, familiar syntax and editor tooling support via Visual Studio and VS Code. It is characterised as a “minimal language” that assists developers in familiarly describing API shapes. More than just a new language, TypeSpec is a platform that facilitates abstraction, encourages code reuse, and leverages modern tooling for rapid development.
Moreover, TypeSpec offers features, including interoperability with industry-standard API definition languages, enhanced productivity through an exceptional developer experience, encapsulation of API patterns into reusable components, extensibility with custom decorators and type templates, and a robust ecosystem for distributing common types and extensions.
TypeSpec has been under development since 2019. Initially known as ADL and later as Cadl (pronounced “cattle”), it was officially named TypeSpec in 2023.
OpenAPI Support
Microsoft introduced TypeSpec to streamline API design guidelines and provide a reusable component for applications across various services. This tool is intuitive, quick to learn, and capable of encapsulating common data types, patterns, and guidelines into high-level components that can be shared across teams or ecosystems. TypeSpec can be compiled into OpenAPI, JSON Schema, Protobuf, or all three simultaneously. Although Microsoft's Azure API toolchain is built around OpenAPI, it encounters challenges in enforcing consistency, promoting reuse, and supporting multiple protocols beyond REST. TypeSpec is highly regarded for its simplicity and productivity, offering variables, macros, and functions for assembling and updating OpenAPI specifications.
Dogfooding
Microsoft has been internally utilising TypeSpec, a tool that is now employed by numerous Azure services, both existing and upcoming, with additional services adopting it each month.
Beyond Azure, the Microsoft Graph team and other departments engaged in various API-related tasks are significant users of TypeSpec.
The TypeSpec team has dramatically benefited from internal users' recommendations. The improvements made through internal usage were too numerous to list. He mentioned that TypeSpec's earliest versions looked quite different from the current iteration, thanks to the feedback they had received over the years.
Microsoft is actively developing the capabilities for TypeSpec, incorporating community feedback before stabilising version 1.0. A key focus is integrating Azure SDK's code generation technology into the TypeSpec project, enabling users to generate clients and servers for their APIs. Microsoft is expanding the TypeSpec language to include features such as the ability to define specific values and use them for API examples. The company is introducing new library features to support streaming APIs, which will facilitate protocols like server-sent events and streaming JSONL.
More in News