An introduction to TypeSpec, a new API definition language

What is TypeSpec?

TypeSpec is an open source language for defining and describing APIs. First introduced in April 2024, the language has been in development since 2019 under the direction of Brian Terlson, a principal software architect for Azure developer experience at Microsoft.

Using TypeSpec, developers can write code that describes API shapes or an API's input and output and then use this code as the basis for implementing APIs. TypeSpec supports the export of TypeSpec definitions to standardized specification languages, such as definitions written in YAML using the OpenAPI specification (OAS). This feature makes it easy to share API definitions across different teams and to reuse them in varying contexts. For instance, developers could recycle the same definition for multiple projects.

TypeSpec has so far remained closely associated with the Microsoft ecosystem. The source code for the language is available through a Microsoft repository on GitHub, and a series of TypeSpec libraries are available for Azure, but not for other major cloud platforms at this time. Additionally, complete TypeSpec support is currently limited to Microsoft developer tools VS Code and Visual Studio.

TypeSpec and TypeScript: A vision for clean code

TypeSpec is inspired by TypeScript, a JavaScript language known for its emphasis on clean, readable code. TypeSpec also bears some resemblances to C#, a language that helped inspire TypeScript.

TypeSpec embodies the TypeScript spirit by focusing on direct and minimal API descriptions. A built-in formatter enforces code consistency, and additional TypeSpec support tools can automatically identify syntax errors and make autocomplete suggestions in real time. These features aim to help developers work faster while adhering to concise API design standards.

TypeSpec also borrows concepts like decorators from TypeScript, making support tasks such as adding metadata to API definitions possible.

Pros and cons of TypeSpec

TypeSpec is not an entirely novel type of tool -- specification languages like OpenAPI and API platforms like Postman have been around for years -- but it does bring its own set of pros and cons to API definitions.

Advantages of TypeSpec

Compared to other platforms for building APIs, TypeSpec stands out for the following key advantages:

• An emphasis on extremely concise code. TypeSpec is an attractive choice for developers who dislike the verbose nature of tools like OpenAPI.
• The ability to compile API descriptions into multiple description languages, including OpenAPI, JSON Schema and Protobuf. This versatility is especially useful when different teams or projects require API descriptions in varying formats.

Since TypeSpec's announcement, some developers have celebrated the language for its shallow learning curve, although that's a subjective assessment. Developers who already know and love TypeScript will likely find TypeSpec especially easy to use because the concepts and coding syntax between the two languages are similar. That said, features like the built-in formatter and real-time code analysis arguably make TypeSpec inherently user-friendly, even for coders who aren't already versed in TypeScript.

Challenges and limitations of TypeSpec

It's hard to think of technical disadvantages to TypeSpec. The only potential limitation to consider at this time is that the language remains tightly associated with Microsoft and has not yet seen much adoption beyond that ecosystem.

For this reason, developers who are not building applications for the Microsoft Azure cloud or who prefer coding tools other than those developed by Microsoft might find TypeSpec harder to work with due to a lack of compatibility between the language and their preferred tools and platforms. In this case, other, more widely established and ecosystem-agnostic description formats such as OpenAPI might be a better option. This could change over time, however, if more vendors embrace TypeSpec and make it a first-class API description language within their products.

Modern software engineers need to learn a variety of languages and tools. For now, developers overwhelmed by these demands shouldn't feel pressure to add TypeSpec to their wheelhouse unless they have a good reason to do so.

Getting started with TypeSpec

To use TypeSpec, you'll need an Integrated Development Environment (IDE) or TypeSpec-compatible coding tool. As noted, these are currently limited to VS Code and Visual Studio.

Once you have one of those tools installed, you can install the TypeSpec extension. You also need to install TypeSpec in your environment, which you can do using npm:

npm install -g @typespec/compiler

From there, enter the following command to create a new TypeScript project:

tsp init

After working through a series of questions that appear in the console, you should install dependencies with:

tsp install

At this point, TypeSpec is set up, and you can begin defining APIs using whichever coding tool you choose to work with.

Chris Tozzi is a freelance writer, research adviser and professor of IT and society who has previously worked as a journalist and Linux systems administrator.