next-rest-framework
Advanced tools
Next REST Framework - Type-safe, self-documenting APIs for Next.js
Type-safe, self-documenting APIs for Next.js
Next REST Framework is an open-source, opinionated, lightweight, easy-to-use set of tools to build type-safe, self-documenting APIs with Next.js. Building OpenAPI specification-compliant APIs can be cumbersome and slow but Next REST Framework makes this easy with auto-generated OpenAPI documents and docs using TypeScript and object schemas.
This is a monorepo containing the following packages / projects:
next-rest-framework packageopenapi.json spec file from your business logic.In order to use Next REST Framework you need to have a Next.js project with the following dependencies installed:
npm install next-rest-framework
To get access to the auto-generated documentation, initialize the docs endpoint somewhere in your codebase. You can also skip this step if you don't want to expose a public API documentation.
// src/app/api/route.ts
import { docsRoute } from 'next-rest-framework';
export const { GET } = docsRoute();
// src/pages/api.ts
import { docsApiRoute } from 'next-rest-framework';
export default docsApiRoute();
This is enough to get you started. Now you can access the API documentation in your browser. Running npx next-rest-framework generate in the project root will generate the openapi.json OpenAPI specification file, located in the public folder. You can create multiple docs endpoints if needed and specify which config to use for the CLI. See the full configuration options of this endpoint in the Docs handler options section.
// src/app/api/todos/route.ts
import { TypedNextResponse, route, routeOperation } from 'next-rest-framework';
import { z } from 'zod';
const TODOS = [
{
id: 1,
name: 'TODO 1',
completed: false
}
];
// Example app router route handler with GET/POST handlers.
export const { GET, POST } = route({
getTodos: routeOperation({
method: 'GET',
// Optional OpenAPI operation documentation.
openApiOperation: {
tags: ['example-api', 'todos', 'app-router']
}
})
// Output schema for strictly-typed responses and OpenAPI documentation.
.outputs([
{
status: 200,
contentType: 'application/json',
schema: z.array(
z.object({
id: z.number(),
name: z.string(),
completed: z.boolean()
})
)
}
])
.handler(() => {
// Type-checked response.
return TypedNextResponse.json(TODOS, {
status: 200
});
}),
createTodo: routeOperation({
method: 'POST',
// Optional OpenAPI operation documentation.
openApiOperation: {
tags: ['example-api', 'todos', 'app-router']
}
})
// Input schema for strictly-typed request, request validation and OpenAPI documentation.
.input({
contentType: 'application/json',
body: z.object({
name: z.string()
})
})
// Output schema for strictly-typed responses and OpenAPI documentation.
.outputs([
{
status: 201,
contentType: 'application/json',
schema: z.string()
},
{
status: 401,
contentType: 'application/json',
schema: z.string()
}
])
.middleware(
// Optional middleware logic executed before request validation.
(req) => {
if (!req.headers.get('authorization')) {
// Type-checked response.
return TypedNextResponse.json('Unauthorized', {
status: 401
});
}
}
)
.handler(async (req) => {
const { name } = await req.json(); // Strictly-typed request.
// Type-checked response.
return TypedNextResponse.json(`New TODO created: ${name}`, {
status: 201
});
})
});
The TypedNextResponse ensures that the response status codes and content-type headers are type-checked. You can still use the regular NextResponse if you prefer to have less type-safety.
// src/pages/api/todos.ts
import { apiRoute, apiRouteOperation } from 'next-rest-framework';
import { z } from 'zod';
const TODOS = [
{
id: 1,
name: 'TODO 1',
completed: false
}
];
// Example pages router API route with GET/POST handlers.
export default apiRoute({
getTodos: apiRouteOperation({
method: 'GET',
// Optional OpenAPI operation documentation.
openApiOperation: {
tags: ['example-api', 'todos', 'pages-router']
}
})
// Output schema for strictly-typed responses and OpenAPI documentation.
.outputs([
{
status: 200,
contentType: 'application/json',
schema: z.array(
z.object({
id: z.number(),
name: z.string(),
completed: z.boolean()
})
)
}
])
.handler((_req, res) => {
// Type-checked response.
res.status(200).json(TODOS);
}),
createTodo: apiRouteOperation({
method: 'POST',
// Optional OpenAPI operation documentation.
openApiOperation: {
tags: ['example-api', 'todos', 'pages-router']
}
})
// Input schema for strictly-typed request, request validation and OpenAPI documentation.
.input({
contentType: 'application/json',
body: z.object({
name: z.string()
})
})
// Output schema for strictly-typed responses and OpenAPI documentation.
.outputs([
{
status: 201,
contentType: 'application/json',
schema: z.string()
},
{
status: 401,
contentType: 'application/json',
schema: z.string()
}
])
// Optional middleware logic executed before request validation.
.middleware((req, res) => {
if (!req.headers.authorization) {
res.status(401).json('Unauthorized'); // Type-checked response.
}
})
.handler((req, res) => {
const { name } = req.body; // Strictly-typed request.
res.status(201).json(`New TODO created: ${name}`); // Type-checked response.
})
});
After running next-rest-framework generate, all of above type-safe endpoints will be auto-generated to your OpenAPI spec and exposed in the documentation:
A recommended way is to write your RPC operation in a separate server-side module where they can be consumed both by the RPC endpoints and directly as server-side functions (server actions):
// src/app/actions.ts
'use server';
import { rpcOperation } from 'next-rest-framework';
import { z } from 'zod';
const TODOS = [
{
id: 1,
name: 'TODO 1',
completed: false
}
];
const todoSchema = z.object({
id: z.number(),
name: z.string(),
completed: z.boolean()
});
export const getTodos = rpcOperation({
tags: ['RPC']
})
.outputs([
{
schema: z.array(todoSchema)
}
])
.handler(() => {
return TODOS; // Type-checked output.
});
export const getTodoById = rpcOperation({
tags: ['RPC']
})
.input(z.string())
.outputs([
{
schema: z.object({
error: z.string()
})
},
{
schema: todoSchema
}
])
.handler((id) => {
const todo = TODOS.find((t) => t.id === Number(id));
if (!todo) {
return { error: 'TODO not found.' }; // Type-checked output.
}
return todo; // Type-checked output.
});
export const createTodo = rpcOperation({
tags: ['RPC']
})
.input(
z.object({
name: z.string()
})
)
.outputs([{ schema: todoSchema }])
.handler(
async ({
name // Strictly-typed input.
}) => {
// Create todo.
const todo = { id: 2, name, completed: false };
return todo; // Type-checked output.
}
);
export const deleteTodo = rpcOperation({
tags: ['RPC']
})
.input(z.string())
.outputs([
{ schema: z.object({ error: z.string() }) },
{ schema: z.object({ message: z.string() }) }
])
.handler((id) => {
// Delete todo.
const todo = TODOS.find((t) => t.id === Number(id));
if (!todo) {
return {
error: 'TODO not found.' // Type-checked output.
};
}
return { message: 'TODO deleted.' }; // Type-checked output.
});
The file path to and RPC route must end with /[operationId]/route.ts. Import the RPC operations in to your RPC route handler:
// src/app/api/rpc/[operationId]/route.ts
import { createTodo, deleteTodo, getTodoById, getTodos } from 'src/app/actions';
import { rpcRoute } from 'next-rest-framework';
export const { POST } = rpcRoute({
getTodos,
getTodoById,
createTodo,
deleteTodo
});
export type RpcClient = typeof POST.client;
Consume the RPC operations directly in your server-side components:
'use server';
import { getTodos, createTodo } from 'src/app/actions';
export default async function Page() {
const todos = await getTodos();
const createTodo = async (name: string) => {
'use server';
return createTodo({ name });
};
// ...
}
The filename of an RPC API route must be [operationId].ts.
// src/pages/api/rpc/[operationId].ts
import { rpcApiRoute } from 'next-rest-framework';
// Example pages router RPC handler.
const handler = rpcApiRoute({
// ...
// Exactly the same as the app router example. You can also inline the RPC operations in this object.
});
export default handler;
export type RpcClient = typeof handler.client;
The RPC routes will also be included in your OpenAPI spec after running next-rest-framework generate.
To achieve end-to-end type-safety, you can use any client implementation that relies on the generated OpenAPI specification, e.g. openapi-client-axios.
For client-rendered components you can use the strongly-typed rpcClient:
'use client';
import { rpcClient } from 'next-rest-framework/rpc-client';
import { type RpcClient } from 'app/api/rpc/[operationId]';
const client = rpcClient<RpcClient>({
url: 'http://localhost:3000/api/rpc'
});
export default function Page() {
// ...
useEffect(() => {
client
.getTodos()
.then(() => {
// ...
})
.catch(console.error);
}, []);
const createTodo = async (name: string) => {
const todo = client.createTodo({ name });
// ...
};
// ...
}
The rpcClient calls can also be easily integrated with any data fetching framework, like React Query or RTKQ.
The following options can be passed to the docsRoute (app router) and docsApiRoute (pages router) functions for customizing Next REST Framework:
| Name | Description |
|---|---|
deniedPaths | Array of paths that are denied by Next REST Framework and not included in the OpenAPI spec. Supports wildcards using asterisk * and double asterisk ** for recursive matching. Example: ['/api/disallowed-path', '/api/disallowed-path-2/*', '/api/disallowed-path-3/**'] Defaults to no paths being disallowed. |
allowedPaths | Array of paths that are allowed by Next REST Framework and included in the OpenAPI spec. Supports wildcards using asterisk * and double asterisk ** for recursive matching. Example: ['/api/allowed-path', '/api/allowed-path-2/*', '/api/allowed-path-3/**'] Defaults to all paths being allowed. |
openApiObject | An OpenAPI Object that can be used to override and extend the auto-generated specification. |
openApiJsonPath | Path that will be used for fetching the OpenAPI spec - defaults to /openapi.json. This path also determines the path where this file will be generated inside the public folder. |
docsConfig | A Docs config object for customizing the generated docs. |
suppressInfo | Setting this to true will suppress all informational logs from Next REST Framework. Defaults to false. |
The docs config options can be used to customize the generated docs:
| Name | Description |
|---|---|
provider | Determines whether to render the docs using Redoc (redoc) or SwaggerUI swagger-ui. Defaults to redoc. |
title | Custom title, used for the visible title and HTML title. |
description | Custom description, used for the visible description and HTML meta description. |
faviconUrl | Custom HTML meta favicon URL. |
logoUrl | A URL for a custom logo. |
ogConfig | Basic customization options for OG meta tags. Requires the following fields: title, type, url, imageUrl. |
The following options can be passed to the routeHandler (app router) and apiRouteHandler (pages router) functions to create new API endpoints:
| Name | Description | Required |
|---|---|---|
GET | PUT | POST | DELETE | OPTIONS | HEAD | PATCH | A Method handler object. | true |
openApiPath | An OpenAPI Path Item Object that can be used to override and extend the auto-generated specification. | false |
The route operation functions routeOperation (app router) and apiRouteOperation (pages router) allow you to define your API handlers for your endpoints. These functions accept an OpenAPI Operation object as a parameter, that can be used to override the auto-generated specification. Calling this function allows you to chain your API handler logic with the following functions.
| Name | Description |
|---|---|
input | A Route operation input function for defining the validation and documentation of the request. |
outputs | An Route operation outputs function for defining the validation and documentation of the response. |
handler | A Route operation-handler function for defining your business logic. |
middleware | A Route operation middleware function that gets executed before the request input is validated. You may chain up to three middlewares together and share data between the middlewares by taking the input of the previous middleware. |
The route operation input function is used for type-checking, validation and documentation of the request, taking in an object with the following properties:
| Name | Description | Required |
|---|---|---|
contentType | The content type header of the request. When the content type is defined, a request with an incorrect content type header will get an error response. | false |
body | A Zod schema describing the format of the request body. When the body schema is defined, a request with an invalid request body will get an error response. | false |
query | A Zod schema describing the format of the query parameters. When the query schema is defined, a request with invalid query parameters will get an error response. | false |
Calling the route operation input function allows you to chain your API handler logic with the Route operation outputs, Route operation middleware and Route operation handler functions.
The route operation outputs function is used for type-checking and documentation of the response, taking in an array of objects with the following properties:
| Name | Description | Required |
|---|---|---|
status | A status code that your API can return. | true |
contentType | The content type header of the response. | true |
schema | A Zod schema describing the format of the response data. | true |
Calling the route operation outputs function allows you to chain your API handler logic with the Route operation middleware and Route operation handler functions.
The route operation middleware function is executed before validating the request input. The function takes in the same parameters as the Next.js router handlers and API routes handlers. Additionally, as a second parameter this function takes the return value of your last middleware function, defaulting to an empty object. Throwing an error inside a middleware function will stop the execution of the handler and you can also return a custom response like you would do within the Handler function. Calling the route operation middleware function allows you to chain your API handler logic with the Handler function. Alternatively, you may chain up to three middleware functions together:
// ...
const handler = route({
getTodos: routeOperation()
.middleware(() => {
return { foo: 'bar' };
})
.middleware((_req, _ctx, { foo }) => {
// if (myCondition) {
// return NextResponse.json({ error: 'My error.' });
// }
return {
foo,
bar: 'baz'
};
})
.handler((_req, _ctx, { foo, bar }) => {
// ...
})
});
The route operation handler function is a strongly-typed function to implement the business logic for your API. The function takes in strongly-typed versions of the same parameters as the Next.js router handlers and API routes handlers. Additionally, as a third parameter this function takes the return value of your last middleware function:
// ...
const handler = route({
getTodos: routeOperation()
.middleware(() => {
return { foo: "bar" };
})
.handler((_req, _ctx, { foo }) => {
// ...
});
});
The rpcRouteHandler (app router) and rpcApiRouteHandler (pages router) functions allow the following options as the second parameter after passing your RPC operations.
| Name | Description | Required |
|---|---|---|
openApiPath | An OpenAPI Path Item Object that can be used to override and extend the auto-generated specification. | false |
openApiOperation | An OpenAPI Path Item Object that can be used to override and extend the auto-generated specification. | false |
The rpcOperation function allows you to define your API handlers for your RPC endpoint. Calling this function allows you to chain your API handler logic with the following functions.
| Name | Description |
|---|---|
input | An RPC operation input function for defining the validation and documentation of the operation. |
outputs | An RPC operation outputs function for defining the validation and documentation of the response. |
handler | An RPC operation handler function for defining your business logic. |
middleware | An RPC operation middleware function that gets executed before the operation input is validated. You may chain up to three middlewares together and share data between the middlewares by taking the input of the previous middleware. |
The RPC operation input function is used for type-checking, validation and documentation of the RPC call. It takes in a A Zod schema as a parameter that describes the format of the operation input. When the input schema is defined, an RPC call with invalid input will get an error response.
Calling the RPC input function allows you to chain your API handler logic with the RPC operation outputs, RPC middleware and RPC handler functions.
The RPC operation outputs function is used for type-checking and documentation of the response, taking in an array of objects with the following properties:
| Name | Description | Required |
|---|---|---|
schema | A Zod schema describing the format of the response data. | true |
name | An optional name used in the generated OpenAPI spec, e.g. GetTodosErrorResponse. | false |
Calling the RPC operation outputs function allows you to chain your API handler logic with the RPC operation middleware and RPC operation handler functions.
The RPC operation middleware function is executed before validating RPC operation input. The function takes in strongly typed parameters typed by the RPC operation input function. Additionally, as a second parameter this function takes the return value of your last middleware function, defaulting to an empty object. Throwing an error inside a middleware function will stop the execution of the handler. Calling the RPC operation middleware function allows you to chain your RPC API handler logic with the RPC operation handler function. Alternatively, you may chain up to three middleware functions together:
// ...
const handler = rpcRoute({
getTodos: rpcOperation()
.middleware(() => {
return { foo: 'bar' };
})
.middleware((_input, { foo }) => {
// if (myCondition) {
// throw Error('My error.')
// }
return {
foo,
bar: 'baz'
};
})
.handler((_input, { foo, bar }) => {
// ...
})
});
The RPC operation handler function is a strongly-typed function to implement the business logic for your API. The function takes in strongly typed parameters typed by the RPC operation input function. Additionally, as a second parameter this function takes the return value of your last middleware function:
// ...
const handler = rpcApiRoute({
getTodos: rpcOperation()
.middleware(() => {
return { foo: "bar" };
})
.handler((_input, { foo }) => {
// ...
});
});
The Next REST Framework CLI supports generating and validating the openapi.json file:
npx next-rest-framework generate to generate the openapi.json file.npx next-rest-framework validate to validate that the openapi.json file is up-to-date.The next-rest-framework validate command is useful to have as part of the static checks in your CI/CD pipeline. Both commands support the following options:
| Name | Description |
|---|---|
--configPath <string> | In case you have multiple docs handlers with different configurations, you can specify which configuration you want to use by providing the path to the API. Example: /api/my-configuration. |
A good practice is to set these in your package.json as both commands are needed:
// package.json
...
"scripts": {
...
"generate": "next-rest-framework generate",
"validate": "next-rest-framework validate",
}
See the changelog in CHANGELOG.md
All contributions are welcome!
ISC, see full license in LICENSE.
5.1.4-beta.1 - 2024-02-20
FAQs
Next REST Framework - Type-safe, self-documenting APIs for Next.js
The npm package next-rest-framework receives a total of 1,527 weekly downloads. As such, next-rest-framework popularity was classified as popular.
We found that next-rest-framework demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CISA extended MITRE’s CVE contract by 11 months, avoiding a shutdown but leaving long-term governance and coordination issues unresolved.
Product
Socket's Rubygems ecosystem support is moving from beta to GA, featuring enhanced security scanning to detect supply chain threats beyond traditional CVEs in your Ruby dependencies.
Research
The Socket Research Team investigates a malicious npm package that appears to be an Advcash integration but triggers a reverse shell during payment success, targeting servers handling transactions.