9c0a8ce730
<!-- 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>
108 lines
4.7 KiB
Markdown
108 lines
4.7 KiB
Markdown
---
|
|
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](https://nodejs.org/api/http.html#http_class_http_serverresponse), (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 code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
|
|
- `res.json(body)` - Sends a JSON response. `body` must be a [serializable object](https://developer.mozilla.org/en-US/docs/Glossary/Serialization)
|
|
- `res.send(body)` - Sends the HTTP response. `body` can be a `string`, an `object` or a `Buffer`
|
|
- `res.redirect([status,] path)` - Redirects to a specified path or URL. `status` must be a valid [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). If not specified, `status` defaults to "307" "Temporary redirect".
|
|
- `res.revalidate(urlPath)` - [Revalidate a page on demand](/docs/basic-features/data-fetching/incremental-static-regeneration.md#on-demand-revalidation) using `getStaticProps`. `urlPath` must be a `string`.
|
|
|
|
## 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:
|
|
|
|
```js
|
|
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](https://developer.mozilla.org/en-US/docs/Glossary/Serialization).
|
|
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:
|
|
|
|
```js
|
|
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.
|
|
|
|
```js
|
|
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:
|
|
|
|
```js
|
|
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:
|
|
|
|
```ts
|
|
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` is `any` 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](/docs/basic-features/typescript.md#api-routes).
|
|
|
|
If you prefer to view your examples within a real projects structure you can checkout our examples repository:
|
|
|
|
- [Basic API Routes](https://github.com/vercel/next.js/tree/canary/examples/api-routes)
|
|
- [API Routes with REST](https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest)
|