ez-api – API development toolkit powered by TypeSpec

I first came across TypeSpec through an article on LinkedIn where someone shared a positive experience using it. This sparked my curiosity, as I was looking for ways to improve API documentation in my current project. The API documentation for our product was relatively weak, making it difficult to ensure consistency and clarity. I decided to experiment with TypeSpec by applying it to a real-world scenario, aiming to simplify API definition and improve collaboration. ℹ️ Disclaimer: This article was written with the assistance of AI to refine structure and clarity. However, all technical content, insights, and project details are based on my personal experience and research. What is TypeSpec? The official documentation states that that TypeSpec is a language and toolset developed by Microsoft for defining data models and service APIs. It provides a structured way to describe the shape and behavior of data and services, ensuring consistency and reducing errors in API development. By leveraging TypeSpec, developers can generate code, documentation, and other artifacts directly from their API definitions, making it easier to maintain and evolve their services. Microsoft itself uses TypeSpec to define APIs for various products, including Azure. The language focuses on specifying the interface of an API—such as operations, request and response models, and error-handling mechanisms—while the actual logic remains in the backend service that processes requests and interacts with the database. Introducing ez-api As I explored TypeSpec, I saw an opportunity to build a development toolkit that would make API creation more straightforward. My goal with ez-api was to: Define multiple APIs without excessive complexity, similar to a monorepo approach Leverage Git to facilitate collaboration among team members Introduce useful scripts to streamline workflows, particularly in continuous integration scenarios By addressing these challenges, ez-api provides a structured yet flexible way to manage API development efficiently. In the following sections, I will delve deeper into how it works and what I learned from the experience. How ez-api works Project setup To develop ez-api, I used the following tools: Visual Studio Code – with the official TypeSpec extension for syntax highlighting and validation TypeSpec CLI – to compile TypeSpec definitions and generate API artifacts Node.js (>= 20) – required for running scripts and dependencies Project structure The ez-api project follows a structured layout to keep API definitions organized and maintainable. Below is an overview of its directory structure: ez-api/ ├── dist/ │ └── my-awesome-api/ │ ├── api-1.0.0-beta.1.yaml │ └── api-1.0.0-beta.1.json ├── doc/ │ └── my-awesome-api/ │ ├── api-x.y.z.yaml │ └── api-x.y.z.json ├── ext/ │ └── .tsp ├── projects/ │ └── my-awesome-api/ │ ├── model/ │ ├── routes/ │ ├── config.json │ ├── main.tsp │ ├── tspconfig-json.yaml │ └── tspconfig-yaml.yaml ├── tools/ │ ├── api-new.ts │ └── postbuild.ts └── package.json Where the main directories are: projects/ – where the TypeSpec, configurations, routes and model files of the API being modeled reside doc/ – the development version of the API in JSON and YAML format dist/ – the official OpenAPI version of the API in JSON and YAML format tools – utility scripts of this toolkit to create and manipulate the API ext – directory where to define useful OpenAPI extensions Real-World scenario: i18n-resources API One of the practical applications of ez-api was to define APIs for handling i18n bundles in an Angular application. The goal was to provide endpoints that: Retrieve UI labels based on the selected language Offer CRUD operations for administrative users to customize translations via a third-party tool For example, the GET route /i18n/bundle definition to retrieve i18n resource by a selector and langTag is shown below: import "@typespec/http"; import "@typespec/openapi"; import "../model/i18n-resource.model.tsp"; import "../model/i18n-locale.model.tsp"; import "./bundle/admin-bundle.route.tsp"; import "../../../ext/badges.tsp"; namespace I18nResourceNamespace; using TypeSpec.Http; using TypeSpec.OpenAPI; @route("/i18n") namespace I18nRoute { @route("/bundle") @summary("Consume bundle resource") @doc(""" Retrieve a bundle resource according selector and langTag taken as input. It's important to note that if a custom bundle is present, it will override the default entries. """) @get op consumeBundle(@query selector: string, @query langTag: string): { @statusCode _: 200; @body result: BaseResponse; }; Through the use of some decorators, a Markdown (or HTML) syntax, it is quite easy to define a route. The real convenience I have identified is the definition of the model, useful to def

Mar 29, 2025 - 14:54

I first came across TypeSpec through an article on LinkedIn where someone shared a positive experience using it. This sparked my curiosity, as I was looking for ways to improve API documentation in my current project. The API documentation for our product was relatively weak, making it difficult to ensure consistency and clarity. I decided to experiment with TypeSpec by applying it to a real-world scenario, aiming to simplify API definition and improve collaboration.

ℹ️ Disclaimer:
This article was written with the assistance of AI to refine structure and clarity. However, all technical content, insights, and project details are based on my personal experience and research.

What is TypeSpec?

The official documentation states that that TypeSpec is a language and toolset developed by Microsoft for defining data models and service APIs. It provides a structured way to describe the shape and behavior of data and services, ensuring consistency and reducing errors in API development. By leveraging TypeSpec, developers can generate code, documentation, and other artifacts directly from their API definitions, making it easier to maintain and evolve their services.

Microsoft itself uses TypeSpec to define APIs for various products, including Azure. The language focuses on specifying the interface of an API—such as operations, request and response models, and error-handling mechanisms—while the actual logic remains in the backend service that processes requests and interacts with the database.

Introducing ez-api

As I explored TypeSpec, I saw an opportunity to build a development toolkit that would make API creation more straightforward. My goal with ez-api was to:

Define multiple APIs without excessive complexity, similar to a monorepo approach
Leverage Git to facilitate collaboration among team members
Introduce useful scripts to streamline workflows, particularly in continuous integration scenarios

By addressing these challenges, ez-api provides a structured yet flexible way to manage API development efficiently. In the following sections, I will delve deeper into how it works and what I learned from the experience.

How ez-api works

Project setup

To develop ez-api, I used the following tools:

Visual Studio Code – with the official TypeSpec extension for syntax highlighting and validation
TypeSpec CLI – to compile TypeSpec definitions and generate API artifacts
Node.js (>= 20) – required for running scripts and dependencies

Project structure

The ez-api project follows a structured layout to keep API definitions organized and maintainable. Below is an overview of its directory structure:

ez-api/
├── dist/
│   └── my-awesome-api/
│       ├── api-1.0.0-beta.1.yaml
│       └── api-1.0.0-beta.1.json
├── doc/
│   └── my-awesome-api/
│       ├── api-x.y.z.yaml
│       └── api-x.y.z.json
├── ext/
│   └── .tsp
├── projects/
│   └── my-awesome-api/
│       ├── model/
│       ├── routes/
│       ├── config.json
│       ├── main.tsp
│       ├── tspconfig-json.yaml
│       └── tspconfig-yaml.yaml
├── tools/
│   ├── api-new.ts
│   └── postbuild.ts
└── package.json

Where the main directories are:

projects/ – where the TypeSpec, configurations, routes and model files of the API being modeled reside
doc/ – the development version of the API in JSON and YAML format
dist/ – the official OpenAPI version of the API in JSON and YAML format
tools – utility scripts of this toolkit to create and manipulate the API
ext – directory where to define useful OpenAPI extensions

Real-World scenario: i18n-resources API

One of the practical applications of ez-api was to define APIs for handling i18n bundles in an Angular application. The goal was to provide endpoints that:

Retrieve UI labels based on the selected language
Offer CRUD operations for administrative users to customize translations via a third-party tool

For example, the GET route /i18n/bundle definition to retrieve i18n resource by a selector and langTag is shown below:

import "@typespec/http";
import "@typespec/openapi";
import "../model/i18n-resource.model.tsp";
import "../model/i18n-locale.model.tsp";
import "./bundle/admin-bundle.route.tsp";
import "../../../ext/badges.tsp";

namespace I18nResourceNamespace;

using TypeSpec.Http;
using TypeSpec.OpenAPI;

@route("/i18n")
namespace I18nRoute {
  @route("/bundle")
  @summary("Consume bundle resource")
  @doc("""
      Retrieve a bundle resource according **selector** and **langTag** taken as input.

      It's important to note that if a custom bundle is present, it will override the default entries.
    """)
  @get
  op consumeBundle(@query selector: string, @query langTag: string): {
    @statusCode _: 200;
    @body result: BaseResponse;
  };

Through the use of some decorators, a Markdown (or HTML) syntax, it is quite easy to define a route.
The real convenience I have identified is the definition of the model, useful to define the route. For example, let see how I defined I18nResource:

import "@typespec/openapi3";

using TypeSpec.OpenAPI;

@example(i18nResourceExample)
model I18nResource {
  /**
   * Resource bundle identifier
   */
  selector: string;

  /**
   * Language identifier according application locales
   */
  langTag: string;

  /**
   * Json object with i18n entries
   */
  bundle: Record;

  /**
   * True if resource is provided by application, false if it's created by customer
   */
  default: boolean;
}

const i18nResourceExample: I18nResource = #{
  selector: "reportingApp",
  langTag: "it-IT",
  bundle: #{ key1: #{ key2: "Label per key 2" }, key3: "Label per key 3" },
  default: true,
};

As you can note, for a Typescript developer it's very easy define a model in Typespec.

Conclusion

The ez-api project showcases how TypeSpec can be leveraged to define and manage APIs in a structured and maintainable way. By using TypeSpec along with this toolkit, I was able to streamline API development while ensuring consistency across multiple services.

If you're interested in exploring the full implementation of ez-api, including the complete definition of the i18n-resources API, you can find the repository here:

➡️ GitHub Repository:

rstanziale / ez-api

API development toolkit powered by TypeSpec

ez-api

A robust API development toolkit powered by TypeSpec, enabling seamless API design and generation.

Overview

ez-api leverages Microsoft's TypeSpec to define and maintain consistent APIs across projects. This toolkit streamlines the API development workflow with powerful developer experience (DX) features.

Features

TypeSpec Integration: First-class support for Microsoft's TypeSpec specification language
Project Generation: Quick scaffolding with predefined archetypes
OpenAPI Compliance: Automatic generation of OpenAPI 3.0 specifications
Developer Tools: Enhanced DX with built-in utilities

Getting Started

Prerequisites

Node.js (v20 or higher)
TypeSpec CLI (npm install -g @typespec/compiler)
Visual Studio Code as editor
Official TypeSpec VSCode extension
Prettier extension for VSCode (optional)

Installation

npm install

Quick Start

Create your first API project:

npm run api:new my-awesome-api

Customize project settings in config.json:

{
    "filename": "api-my-awesome-api",
    "version": "1.0.0-beta.1"
}

Build OpenAPI specifications:

npm run compile:my-awesome-api

Project Commands

api-new to…

View on GitHub

Future Improvements

While ez-api already simplifies API development, I have a few improvements in mind:

OpenAPI Import – The ability to import an existing OpenAPI specification and automatically generate the corresponding ez-api structure. This would help teams transition smoothly from OpenAPI-based workflows to TypeSpec.
Enhanced Tooling – Additional scripts and automation to further integrate with CI/CD pipelines and improve developer experience.

TypeSpec is a powerful tool, and I believe it has the potential to become a key component in modern API development workflows. If you have any feedback or ideas for improvement, feel free to leave a comment or open a question issue in the GitHub repository!