DEV Community: Roberto B. Stanziale

ez-api – API development toolkit powered by TypeSpec

Roberto B. Stanziale — Sat, 29 Mar 2025 13:28:06 +0000

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 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/
│   └── <ext-name>.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/<api-name> – where the TypeSpec, configurations, routes and model files of the API being modeled reside
doc/<api-name> – the development version of the API in JSON and YAML format
dist/<api-name> – 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

Available commands

The ez-api toolkit provides a set of commands to facilitate API development:

api:new <api-name> – Creates a new API project with the specified name, setting up the necessary directory structure and configuration files
compile-yaml:<api-name>/compile-json:<api-name> – Generates developer preview YAML or JSON files in the doc/<api-name> directory
compile:<api-name> – Generates production ready OpenAPI-compliant YAML and JSON files in the dist/<api-name> directory

These commands simplify the workflow, making it easier to bootstrap new API projects and generate the required artifacts with minimal effort.

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";

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<I18nResource>;
  };

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<unknown>;

  /**
   * 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
Import OpenAPI Specs: Import existing OpenAPI specifications into TypeSpec projects
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

pnpm install

Quick Start

Create your first API project:

pnpm run api:new my-awesome-api

or import an existing OpenAPI specification:

pnpm run api:import my-awesome-api path/to/openapi.yaml

Customize project settings in config.json:

…

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! 🚀

ez-flow – Typescript library for a workflow engine

Roberto B. Stanziale — Sun, 25 Feb 2024 14:42:44 +0000

This library was heavily inspired to j-easy/easy-flows in the Java world.

Definitions

A Workflow is a collection of Work Units must be run tu achieve a given purpose.

Each Work unit implements a behaviour and interacts with outer environment and the other units by the means of a Context exchanged between them. You can place each unit in a flow applying some logic to control it.

That is you can place unit in a sequential flow, in a conditional one, in a parallel one and so on.

At the end of this "chain" we obtain the final result.

In this library are actually available the following flow constructs:

Sequential Flow
Conditional Flow
Iterative Flow
Parallel Flow

How to apply a flow?

Suppose you have defined a work unit called PrintMessageWork that implements Work. It takes a message and its call method prints it:

import {
  Work,
  WorkContext,
  WorkReport,
  DefaultWorkReport,
  WorkStatus,
} from '@rs-box/ez-flow';

export class PrintMessageWork implements Work {
  private message: string;

  constructor(message: string) {
    this.message = message;
  }

  getName() {
    return 'print message';
  }

  async call(workContext: WorkContext): Promise<WorkReport> {
    console.log(this.message);
    return new DefaultWorkReport(WorkStatus.COMPLETED, workContext);
  }
}

Use case

To test the library, a use case scenario was built in which, given a list of Italian cities, I wish to perform certain operations on each city and produce results.

To achieve this, it was important to first define the available inputs and what the workflow wanted to obtain, in this case the cumulative data on the regions to which the cities belong.

Installation

npm install @rs-box/ez-flow

Workflows definition

Specifically, three workflows were built:

Main workflow
Loop over cities workflow
Operations workflow

Main

This is the main workflow, a Sequential Flow that performs two operations:

Validate the context given as input (ValidateContext unit).
Calling the Loop over cities workflow.

Loop over cities

This is a Repeat Flow, it will run until the IsNotLastCity predicate returns a negative value

Operations city

This is a Parallel Flow that executes the list of units passed as input, in the specific case of this test it will perform the following actions:

Print the city name
Update the cumulative region data.

Complete

This is the complete workflow resulting from the combination of those shown above.

Result

Finally, the workflow described above is translated as follows:

const workflow = SequentialFlow.Builder.newFlow()
  .withName('Main workflow')
  .addWork(new ValidateContextWork())
  .addWork(
    RepeatFlow.Builder.newFlow()
      .withName('Loop over cities')
      .withWork(
        ParallelFlow.Builder.newFlow()
          .withName('Operations city')
          .withWorks([new PrintCityWork(), new RegionCity()])
          .build(),
      )
      .until(new IsNotLastCityPredicate())
      .build(),
  )
  .build();

Source code

You can find the full source code for this scenario here:

rstanziale / ez-flow-test

Application for testing ez-flow

ez-flow-test

This application test aims to demonstrate @rs-box/ez-flow functions.

Use case

To test the library, a use case scenario was built in which, given a list of Italian cities, I wish to perform certain operations on each city and produce results.

To achieve this, it was important to first define the available inputs and what the workflow wanted to obtain, in this case the cumulative data on the regions to which the cities belong.

Workflows definition

Specifically, three workflows were built:

Main workflow
Loop over cities workflow
Operations workflow

Main

This is the main workflow, a Sequential Flow that performs two operations:

Validate the context given as input (ValidateContext unit).
Calling the Loop over cities workflow.

Loop over cities

This is a Repeat Flow, it will run until the IsNotLastCity predicate returns a negative value

Operations city

This is a Parallel Flow that executes the list of units…

View on GitHub

ez-bundle – Javascript tool to research JSON keys in a target directory

Roberto B. Stanziale — Sat, 20 Jan 2024 18:15:16 +0000

As a web developer, the task of internationalizing a web application can often lead to the accumulation of large and unwieldy language bundles over time. These bundles, containing key-value pairs representing translated strings, can become outdated or unused as the application evolves.

Have you ever wondered: Are all JSON keys still being used by my application?

This tool addresses this issue by providing a simple yet effective means to verify whether a specified directory contains all the keys defined in a JSON file provided as input.

It helps ensure that your language bundles are accurate, up-to-date, and efficiently utilized, minimizing the risk of translation errors and inconsistencies.

How it works

In order to be executed, it needs three things:

A JSON file containing your bundle of keys to verify
A target directory where you want to look for the keys in the bundle
A list of comma-separated file extensions to search for

After the execution, this utility will create an entries-not-found.txt file containing the unused keys as shown below:

widget.caseDetail.details
widget.caseDetail.identifier
widget.caseDetail.priority
widget.caseDetail.progressBar
...

How to execute it

The following command is necessary:

node index.js bundle.json src/ js,ts,html

Where bundle.json and src/ are examples of arguments passed as input to the script, and js,ts,html is an optional argument, otherwise, the default is ts,html.

Performance

For large bundles, it may take a while, for example:

[2023-09-14T10:34:22.663Z] [INFO] Number of keys: 1422
[2023-09-14T10:34:22.666Z] [INFO] Starting process...
[2023-09-14T10:51:52.683Z] [INFO] End process!

In an Angular application using the ngx-translate library, with 1422 keys and more than 950 files to scan, it takes about 17 minutes to complete.

Of course, the script could always be improved from a performance point of view. It should be okay as an initial version because I don't expect it to be executed that often 😉

Constraints

Currently, this tool only works on Linux shells because it uses the grep command internally. For Windows, you can run it on shells like git bash.

Repository

Here you can find the script, download it, try it or use it for yourself:

rstanziale / ez-bundle

Given a json file, it performs a search for its keys in a target directory taken as input.

ez-bundle

As a web developer I found myself in the situation of internationalizing a web application, and clearly after a few years the language bundles can grow out of proportion. It is also possible that the application has been modified, refactored, etc...

Now, are all the keys in the language bundles still being used?

This tool allows you to answer that question.

How it works

To be executed, it needs three things:

A JSON file containing your bundle of keys to verify
A target directory where you want to look for the keys in the bundle
A list of file extensions comma separated to search for

After execution, this utility will create a entries-not-found.txt file containing the unused keys as shown below:

widget.caseDetail.details
widget.caseDetail.identifier
widget.caseDetail.priority
widget.caseDetail.progressBar

How to execute it

It is necessary to run the command:

node index.js bundle.json src/ js,ts,html

Where bundle.json and src/ are examples of…

View on GitHub