<!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation or adding/fixing Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> closes #48416 ### What? Standardize the "Note" format in the Next.js documentation for improved consistency and readability. ### Why? There are currently four different variations of "Note" formatting in the documentation. Standardizing to a single format will improve the overall experience for users. ### How? Update all instances of "Note" in the documentation to follow the most common format, `**Note**:` (used in 27 files). This will involve updating the following variations: - `Note` (12 files) - `Note:` (20 files) - `**Note:**` (21 files) --------- Co-authored-by: Steven <steven@ceriously.com>
4.7 KiB
description |
---|
API Routes include a set of Express.js-like methods for the response to help you creating new API endpoints. Learn how it works here. |
API Routes Response Helpers
The Server Response object, (often abbreviated as res
) includes a set of Express.js-like helper methods to improve the developer experience and increase the speed of creating new API endpoints.
The included helpers are:
res.status(code)
- A function to set the status code.code
must be a valid HTTP status coderes.json(body)
- Sends a JSON response.body
must be a serializable objectres.send(body)
- Sends the HTTP response.body
can be astring
, anobject
or aBuffer
res.redirect([status,] path)
- Redirects to a specified path or URL.status
must be a valid HTTP status code. If not specified,status
defaults to "307" "Temporary redirect".res.revalidate(urlPath)
- Revalidate a page on demand usinggetStaticProps
.urlPath
must be astring
.
Setting the status code of a response
When sending a response back to the client, you can set the status code of the response.
The following example sets the status code of the response to 200
(OK
) and returns a message
property with the value of Hello from Next.js!
as a JSON response:
export default function handler(req, res) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
Sending a JSON response
When sending a response back to the client you can send a JSON response, this must be a serializable object. In a real world application you might want to let the client know the status of the request depending on the result of the requested endpoint.
The following example sends a JSON response with the status code 200
(OK
) and the result of the async operation. It's contained in a try catch block to handle any errors that may occur, with the appropriate status code and error message caught and sent back to the client:
export default async function handler(req, res) {
try {
const result = await someAsyncOperation()
res.status(200).json({ result })
} catch (err) {
res.status(500).json({ error: 'failed to load data' })
}
}
Sending a HTTP response
Sending an HTTP response works the same way as when sending a JSON response. The only difference is that the response body can be a string
, an object
or a Buffer
.
The following example sends a HTTP response with the status code 200
(OK
) and the result of the async operation.
export default async function handler(req, res) {
try {
const result = await someAsyncOperation()
res.status(200).send({ result })
} catch (err) {
res.status(500).send({ error: 'failed to fetch data' })
}
}
Redirects to a specified path or URL
Taking a form as an example, you may want to redirect your client to a specified path or URL once they have submitted the form.
The following example redirects the client to the /
path if the form is successfully submitted:
export default async function handler(req, res) {
const { name, message } = req.body
try {
await handleFormInputAsync({ name, message })
res.redirect(307, '/')
} catch (err) {
res.status(500).send({ error: 'failed to fetch data' })
}
}
Adding TypeScript types
You can make your response handlers more type-safe by importing the NextApiRequest
and NextApiResponse
types from next
, in addition to those, you can also type your response data:
import type { NextApiRequest, NextApiResponse } from 'next'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.status(200).json({ message: 'Hello from Next.js!' })
}
Note
: The body of
NextApiRequest
isany
because the client may include any payload. You should validate the type/shape of the body at runtime before using it.
To view more examples using types, check out the TypeScript documentation.
If you prefer to view your examples within a real projects structure you can checkout our examples repository: