next-rest-framework

Next REST Framework

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

Table of contents

• Table of contents
• Overview
• Features
  • Lightweight, type-safe, easy to use
• Installation
• Getting started
  • Initialize client
  • Initialize catch-all handler
  • Add an API Route
• Config options
• Route config
  • Method handlers
    • Input
    • Output object
    • Handler
• Middlewares
  • Global middleware
  • Route middleware
  • Method middleware
• Error handlers
  • Global error handler
  • Route error handler
  • Method error handler
• 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({
  //  apiRoutesPath: "src/pages/api", // Only needed if using the src/ folder.
});

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: z.object({
        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.

Changelog

See the changelog in CHANGELOG.md

Contributing

All contributions are welcome!

License

ISC, see full license in LICENSE.

Changelog

0.4.2 - 2023-03-21

Fixed

• Fix bug with middlewares and error handlers that responded to the API request and the execution was not stopped.