Charge your APIs Volume 10: Crafting API Definitions with TypeSpec

As we approach the summer holiday, I thought of wrapping up the series o with a deep dive into the crafting of API definitions with a example for retail domains. We'll explore the powerful capabilities of Microsoft TypeSpec and its transformation to OpenAPI. Let's go!

Understanding TypeSpec

Microsoft's TypeSpec is a robust language-agnostic tool that allows us to define data models and types. It helps to enforce type-safe design, minimise potential errors, and simplify API maintenance. Its main purpose is to provide a way of defining types and data structures that can be understood and shared across different programming languages.

The crux of TypeSpec is to allow developers to define their data models in one place, keeping them synchronised, less prone to errors, and easy to maintain. TypeSpec creates a "source of truth" for your data models and types.

But be careful, TypeSpec is still under development. The version of the TypeSpec compiler used in this introduction is 0.45.2.

Crafting Retail Models with TypeSpec

In the context of a retail API, these models may represent customers, products, orders, and more. Defining these models accurately is crucial for efficient API functioning.

For instance, the TypeSpec model for a customer could look like this:

We can also have a representation of Problem+JSON standardisation of error representation in an API description.

In case of reusability these two models are separated in different tsp files in a models folder. This gives us the possibilities to import the models into the TypeSpec definition.

But, to start with this definition, we need to prepare our workplace a little.

First of all, we need the TypeSpec compiler.

We also need to install the VSCode extensions.

We then create a folder called customer_http. In this folder we initialise TypeSpec.

To do this, we use the Generic Rest API template. We select @typespec/openapi3 as the library. Then we need to install the dependencies. This gives us the following structure.

We describe the definition in main.tsp and also include the models in this file. As we can see in the example.

From TypeSpec to OpenAPI

Once we've crafted our TypeSpec models, we can transform them into other formats. One of the most popular choices for API specifications is OpenAPI.

We translate the TypeSpec definition into OpenAPI one by using tsp compile .. This creates a openapi.yaml file in a tsp-output folder. Following we can have a look at the transformed OpenAPI definition.

Wrapping Up

In essence, Microsoft TypeSpec provides a language-agnostic method to define models, which you can then translate into other API specifications like OpenAPI. This creates a comprehensive and flexible approach to API development, fitting various use cases and technology stacks.

As I bid adieu for the summer, I leave you with the excitement of exploring TypeSpec and its incredible capabilities. Here's to a summer of innovation and relaxation! Stay tuned, and we'll see you after the break with more engaging topics from the world of APIs!

References

GitHub - danielkocot/typespec-playground-retail: A playground for TypeSpec

Introduction | TypeSpec

RFC 7807: Problem Details for HTTP APIs