[tech] Typespec for API first development

About Typespec

Typespec is a new language from Microsoft to define APIs. I've been prototyping with typespec for a few projects and am already sold on the benefits. I’ll introduce the language and tool ecosystem in this article.

In a nutshell, typespec allows you to define a schema with models (entities) and operations (actions) at a high level. Typespec can emit API schemas for targets like OpenAPI 3, Protobuf and others. I've been exclusively using OpenAPI for many years and even for a single protocol, typespec brings many benefits.

model Store {
  name: string;
  address: Address;
}

model Address {
  street: string;
  city: string;
}

@route("/stores")
interface Stores {
  list(@query filter: string): Store[];
  read(@path id: Store): Store;
}        

Advantages

Concise language

Typespec is inspired by typescript and is fairly concise. The generated OpenAPI for my projects was around twice in length compared to what was declared in typespec. In OpenAPI, repeating the same errors becomes cumbersome while this was easier in typespec.

Typespec supports namespaces, cross file imports, model composition via inheritance and templating (copying). This rich language helps make APIs concise relative to YAML for OpenAPI.

Tooling

The typespec compiler can be installed as a node package. There are libraries for http, rest and OpenAPI which provide enhanced functionality. The compiler provides errors and warnings making it easy to get quick feedback and iterate quickly.

VS Code has good tooling support for the language as of now along with cli based tools. If your target output is OpenAPI specs, you can continue using any existing tooling in your toolchain as well, like code generators from OpenAPI.

A formatter is provided as part of standard tooling making consistency possible.

Tooling is still not very mature though. Plugins for IDEs like intellij are still not available. However since typespec uses LSP tooling should follow soon.

APIs at scale

Typespec will really provide value in companies with different distributed teams working on APIs. A central team can implement common models and codified standards. Other teams can then extend the models with custom features.

Code reviews and validation of types becomes much simpler with types compared to yaml files.

API versioning

Evolution of APIs is possible with first class versioning support. It is possible to have a single file with multiple versioned models, operations and more. Adding, removing renames and other changes are supported via the library extensions. A versioned typespec specification can generate many independently versioned OpenAPI versions.

Extensibility with libraries

The typespec language is small and there is tooling for creation of libraries which can include

• Typespec types for sharing definitions
• Decorators similar to annotations that can add custom behavior
• Emitters for different targets
• Diagnostics, Linters for rule checks regarding API definitions like naming conventions and more.

Typespec libraries can be written in typescript or javascript. Based on hooks configured the library has access to the AST and APIs to be able to customize behavior. The current extensions for HTTP, REST, and OpenAPI3 are built as libraries and hence the extensibility tooling should be fairly mature.

Getting started

The getting started page and docs on the main page have good examples. For a tech talk view?

https://youtu.be/yfCYrKaojDo

For a sample advanced project with common models and versioning see the project I’ve been testing with - typespec-monorepo. I'll add additional patterns as I continue to explore typespec.

API First enabler

I'm a strong proponent of API first (compared to code first) approaches to development. Figuring out what to build before actually starting implementation helps build more intuitive APIs. Using tools like typespec can uplift how teams work with APIs making the process approachable and hence adoption of standards less painful.

Smithy is an alternative to typespec from Amazon. It has fairly similar goals and features. It was released publicly over a year ago. However the website does not have the finesse of the typespec project and I eventually ended up spending more time with typespec instead. Smithy also has a great ecosystem. Typespec is built using typescript, which smithy is java based and that might be a consideration for teams that need custom tooling. Either tool will help with an API first approach at scale.

Cross posted from blog - https://www.rahul.revos.name/p/tech-typespec-for-api-first-development