Contract-First Approach with Node.js and OpenAPI for REST Services

When you create a Rest Service, it’s important to specify the resources and routes. This can happen either before you start building the service or after each iteration. One popular way to define an API is by using the **OpenAPI Specification, which is essentially a file (in YAML or JSON) that lays out the routes and resources of your API.**

This OpenAPI Specification is handy when you share your API with other teams. They can seamlessly integrate it into their applications without getting into the nitty-gritty of your internal workings. If you’re new to the OpenAPI Specification, feel free to check out the official documentation.

As mentioned earlier, there are two options when working with the OpenAPI Specification:

• Dynamically generating it through specific frameworks after the REST-Service has been developed (API-First)
• Manually specifying it during product design (Contract-First)

If you opt for the Contract-First Approach, where you define the API contract before implementation, you will have several advantages:

1. Parallel Development: Other teams can start work before the actual development of the REST service, thanks to the predefined contract.
2. Single Source of Truth: The contract acts as a central reference point, ensuring consistency between teams and reducing the chances of misunderstandings.
3. Resource Model Generation and Type-Safe Queries: Automatically generate resource models, queries and validation logic from the contract, reducing manual effort.

Node.js Tools for Contract-First API

You might be familiar with Spring Boot, a Java framework often utilized for building Restful APIs. While the **open-api-generator is a robust tool providing various features, including generating resource models, controller interfaces, executing validation logic, and even creating model and API tests, it’s important to note that the Node.js version is somewhat limited. Primarily, it focuses on generating TypeScript models.**

As our goal is to externalize as much logic as possible, encompassing validation logic, the generation of HTTP clients for service requests, and even setting up a fake API server for frontend testing, we need to explore other tools.

1. Loopback.io

“LoopBack is an award-winning, highly extensible, open-source Node.js and TypeScript framework based on Express.” ~ LoopBack Documentation

• + Powerful CLI: Offers a robust Command-Line Interface for efficiently generating TypeScript models, services, controllers, and validation logic based on OpenAPI Specifications.
• + Modular Integration: Features various submodules facilitating seamless integration with databases, authentication, monitoring, and more.
• - Learning Curve: Proper utilization of all features may entail a learning curve.
• - Ecosystem Binding: While extensible, there is a risk of potential limitations when integrating custom functionalities outside the Loopback ecosystem.

2. Express-Openapi

“An unopinionated OpenAPI framework for express” ~ express-openapi

• + High Performance and Reliability: Exhibits a robust feature set, including support for validation and security. The extensive testing framework guarantees stability and quality in implementation.
• + Simple Configuration: Empowers users to generate API paths and models dynamically with a straightforward configuration, providing flexibility without unnecessary complexity.
• - Express.js Centric Scope: While primarily tailored to Express.js & Koa.js, the framework does offer additional packages related to contract-first development.
• - Challenging Documentation: The documentation currently relies on markdown in a GitHub repository. This requires navigating through various files and features, which might be time-consuming.

3. Kubb.dev

“Generate SDKs for all your APIs — OpenAPI to TypeScript, React-Query, Zod, Zodios, Faker.js, MSW and Axios.” ~ Kubb

All the previously mentioned tools, including Loopback and Express-OpenAPI, operate as frameworks that directly integrate your OpenAPI specification into their structure. While this approach offers convenience, it may come at the expense of flexibility. However, Kubb (CLI tool) with the capability to generate code for different frameworks brings a completely new perspective.

In contrast to frameworks, Kubb offers a more versatile solution, allowing users to tailor their generated components to specific needs.

• + Seamless Integration: Kubb effortlessly integrates with various frameworks. It enables the generation of TypeScript models, **Zod validation objects, supports validation of incoming requests with [Zodious for Express servers](https://www.zodios.org/docs/server/express-app), and facilitates typed queries using [Axios Client](https://axios-http.com/docs/intro) and [Tanstack-queries](https://tanstack.com/query/latest+)**. Additionally, it also can generate a fake api using MSW, serving mock data generated with Faker.js for frontend testing.
• + Highly Customizable: The generated code is highly customizable through templates, and most configurations can be easily handled through some simple adjustments in the kubb.config.ts file
• - New Tool: Kubb is quite a new and feature extensive tool. However, it is actively maintained, and any issues are promptly addressed from the contributors.

Building a Rest-Service with the Contract-First Approach by using Kubb.dev

Given Kubb’s robust capabilities, the main strategy is to leverage its power for a streamlined development process. The goal is to delegate various tasks to the Kubb tool, ensuring that essential components like validation logic, model types, and even the Axios client/React queries for the frontend are generated effortlessly through the CLI.

By doing so, the focus remains on creating the Express server and implementing the necessary business logic, while Kubb takes care of the heavy lifting in terms of code generation and standardization.

Generating models, controller interfaces and validation logic with Kubb (Logos are under trademark and belong to the respective owners)

The image above is a sneak peak on how the tool can be invoked to create a full-stack application, emphasizing the OpenAPI file as the single source of truth. The goal is to minimize manual labor for increasing the efficiency and simplicity of the development process.

Stay tuned for an upcoming article that will dive deeper into the kubb.dev tool (Will be linked to this article soon). It will guide you through building a full-stack application using the contract-first approach with the Kubb CLI tool. Additionally, a GitHub starter project (currently WIP)will be made available, allowing you to test the tool firsthand.

I hope you enjoyed reading this article. If you have any questions or encounter issues, feel free to reach out. Until next time!