next-rest-framework: A TypeScript repository from Cajuteq

Next REST Framework

Type-safe, self-documenting REST APIs for Next.js

Table of contents
Overview
Features
- Lightweight, type-safe, easy to use
Installation
Getting started
Config options
Route config
- Method handlers
Middlewares
Error handlers
Changelog
Contributing
License

Overview

Next REST Framework is an open-source, opinionated, lightweight, easy-to-use set of tools to build type-safe, self-documenting HTTP REST APIs with Next.js. Building OpenAPI specification-compliant REST APIs can be cumbersome and slow but Next REST Framework makes this easy with auto-generated OpenAPI documents and Swagger UI using TypeScript and object schemas.

This is a monorepo containing the following packages / projects:

The primary next-rest-framework package
A development test application

Features

Lightweight, type-safe, easy to use

Designed to work with TypeScript so that your request bodies, responses, headers etc. are strongly typed.
Object-schema validation with popular libraries like Zod or Yup. These schemas are automatically converted to JSON schema format for the auto-generated OpenAPI specifications.
Supports auto-generated openapi.json and openapi.yaml documents for which you can include your existing OpenAPI specification.
Supports any kind of middleware logic that you want to use for authentication etc. See more in Middlewares. Also works with other Next.js server-side libraries, like NextAuth.js.
Fully customizable - You can decide which routes Next REST Framework will use to serve your API docs etc. and it can be easily customized to work with any kind of existing Next.js REST API.

Installation

npm install --save next-rest-framework

Getting started

Initialize client

To use Next REST Framework you need to initialize the client somewhere in your Next.js project. The client exposes all functionality of the framework you will need:

// next-rest-framework/client.ts

import { NextRestFramework } from 'next-rest-framework';

export const { defineCatchAllHandler, defineEndpoints } = NextRestFramework();

The complete API of the initialized client is the following:

Name	Description
`defineCatchAllHandler`	A function used to generate your single catch-all API route. Must be used in the root of your API routes folder in the following path `pages/api/[[...next-rest-framework]].ts`.
`defineEndpoints`	Used for all other API routes that you want to use Next REST Framework for. Can also be used in other catch-all API routes.

Initialize catch-all handler

To initialize Next REST Framework you need to export and call the defineCatchAllHandler function from a root-level optional catch-all API route:

// pages/api/[[...next-rest-framework]].ts

import { defineCatchAllHandler } from 'next-rest-framework/client';

export default defineCatchAllHandler();

This is enough to get you started. By default Next REST Framework gives you three API routes with this configuration:

/api: Swagger UI using the auto-generated OpenAPI spec.
/api/openapi.json: An auto-generated openapi.json document.
/api/openapi.yaml: An auto-generated openapi.yaml document.

All of these are configurable with the Config options that you can pass for your NextRestFramework client. You can also use your existing catch-all logic simply by passing a Route config to your defineCatchAllHandler if you want to use e.g. custom 404 handlers, redirections etc.

Add an API Route

// pages/api/todos.ts

import { defineEndpoints } from 'next-rest-framework/client';
import { z } from 'zod';

const todoSchema = z.object({
  id: z.string(),
  name: z.string(),
  completed: z.boolean()
});

export default defineEndpoints({
  GET: {
    output: [
      {
        status: 200,
        contentType: 'application/json',
        schema: z.array(todoSchema)
      }
    ],
    handler: ({ res }) => {
      // Any other content type will lead to TS error.
      res.setHeader('content-type', 'application/json');

      // Any other status or JSON format will lead to TS error.
      res.status(200).json([
        {
          id: 'foo',
          name: 'bar',
          completed: true
        }
      ]);
    }
  },
  POST: {
    input: {
      contentType: 'application/json',
      body: z.object({
        name: z.string()
      }),
      query: {
        page: z.number()
      }
    },
    output: [
      {
        status: 201,
        contentType: 'application/json',
        schema: todoSchema
      }
    ],
    handler: ({
      res,
      req: {
        body: {
          name // Any other attribute will lead to TS error.
        },
        query: {
          page // Any other attribute will lead to TS error.
        }
      }
    }) => {
      // Any other content type will lead to TS error.
      res.setHeader('content-type', 'application/json');

      // Any other status or JSON format will lead to TS error.
      res.status(201).json({
        id: 'foo',
        name,
        completed: false
      });
    }
  }
});

These type-safe endpoints will be now auto-generated to your OpenAPI spec and Swagger UI!

Config options

The optional config options allow you to customize Next REST Framework. The following options can be passed as a parameter for your NextRestFramework client in an object:

Name	Description
`openApiSpec`	An OpenAPI Object that can be used to override and extend the auto-generated specification.
`openApiJsonPath`	Custom path for serving `openapi.json` file. Defaults to `/api/openapi.json`.
`openApiYamlPath`	Custom path for serving `openapi.yaml` file. Defaults to `/api/openapi.yaml`.
`swaggerUiPath`	Custom path for service Swagger UI. Defaults to `/api`.
`exposeOpenApiSpec`	Setting this to `false` will serve none of the OpenAPI documents neither the Swagger UI. Defaults to `true`.
`middleware`	A global middleware for all of your API routes. See Global middleware for more information.
`errorHandler`	A Global error handler for all of your API routes. Defaults to a basic error handler logging the errors in non-production mode.
`suppressInfo`	Setting this to `true` will suppress all informational logs from Next REST Framework. Defaults to `false`.
`apiRoutesPath`	Absolute path to the directory where your API routes are located - defaults to `pages/api`.

Route config

The route config parameters define an individual route, applicable for all endpoints (methods) that are using that route:

Name	Description	Required
`GET \| PUT \| POST \| DELETE \| OPTIONS \| HEAD \| PATCH \| TRACE`	A Method handler object.	`true`
`middleware`	A Middleware function that takes in the return values from your Global middleware.	`false`
`errorHandler`	A Route error handler for this API route, overriding the Global error handler.	`false`
`openApiSpec`	An OpenAPI Path Item Object that can be used to override and extend the auto-generated and higher level specifications.	`false`

Method handlers

The method handler parameters define an individual endpoint:

Name	Description	Required
`input`	An Input object object.	`false`
`output`	An array of Output objects.	`true`
`middleware`	A Middleware function that takes in the return values from both your Global middleware and Route middleware.	`false`
`handler`	Your Handler function that takes in your typed request, response and Middleware parameters and contains all of your business logic.	`true`
`errorHandler`	A Method error handler for this method, overriding both the Global error handler and Route error handler.	`false`
`openApiSpec`	An OpenAPI Operation object that can be used to override and extend the auto-generated and higher level specifications.	`false`

Input

The input object is used for the validation of the incoming request:

Name	Description	Required
`contentType`	The content type that the request must have - request with no content type or incorrect content type will get an error response.	`true`
`body`	A Zod or Yup schema describing the format of the request body.	`true`
`query`	A Zod or Yup schema describing the format of the query parameters.	`false`

Output object

The output objects define what kind of responses you are allowed to return from your API handlers:

Name	Description	Required
`status`	A possible status code that your API can return - using other status codes will lead to a TS error.	`true`
`contentType`	The content type of the response - using other content-types will lead to a TS error.	`true`
`schema`	A Zod or Yup schema describing the format of the response data. A response format not matching to the schema will lead to a TS error.	`true`

Handler

The handler function takes care of your actual business logic, supporting both synchronous and asynchronous execution and taking in an object with three strongly typed parameters:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	An object containing the strongly-typed combined response of your Global middleware, Route middleware and Method middleware. The parameters can also be overridden in the different middleware layers with the Method middleware taking precedence over the Route middleware and route middleware taking precedence over Global middleware

Middlewares

The middleware functions can be used for any kind of middleware logic, like adding authentication etc. for your API. In addition, they can be used to add additional typed parameters for your API route handlers. They support both asynchronous and synchronous execution.

// A global middleware, route middleware or method middleware.
middleware: () => ({
  foo: 'bar'
});
// A method handler (given that the middleware above is either in the same API route or method, or is a global middleware).
handler: ({
  params: {
    foo // string
  }
}) => {
  // Your logic.
};

Global middleware

The global middleware function takes in an object with two attributes and optionally returns an object of any form:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.

Route middleware

The route middleware function takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.
`params`	The type of an object returned by your Global middleware.

Method middleware

The method middleware function takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	The type of a combined object returned by both your Global middleware and Route middleware.

Error handlers

The error handler functions can be used for custom error handling. They support both asynchronous and synchronous execution.

// A global error handler, route error handler or method error handler.
errorHandler: ({ req, res, params }) => {
  // Your error handling logic.
};

Global error handler

The global error handler takes in an object with two attributes:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.

Route error handler

Route error handler can be used to override your global error handler. The route error handler takes in an object with three attributes:

Name	Description
`req`	A plain `NextApiRequest` object.
`res`	A plain `NextApiResponse` object.
`params`	The type of a combined object returned by both your Global middleware and Route middleware.

Method error handler

Method error handler can be used to override both your global error handler and route error handler. The method error handler takes in an object with three attributes and optionally returns an object of any form:

Name	Description
`req`	A strongly-typed `NextApiRequest` object containing the typed body and query parameters of your request.
`res`	A strongly-typed `NextApiResponse` object that allows you to use only pre-defined status codes, `Content-Type` headers and response data formats from the current method handler.
`params`	The type of a combined object returned by your Global middleware, Route middleware and Method middleware.

Cajuteq/next-rest-framework

Next REST Framework

Table of contents

Lightweight, type-safe, easy to use