dac715e8f7
* Add flag to disable API warning This flag is useful when you are using an external API resolver like express when defining an API route, since the native functionality doesn't realize that the API actually sent a response. A very simple use case example https://github.com/PabloSzx/next-external-api-resolver-example fixes #10589 * Update api-middlewares.md Co-authored-by: Tim Neutkens <tim@timneutkens.nl>
118 lines
3.1 KiB
Markdown
118 lines
3.1 KiB
Markdown
---
|
||
description: API Routes provide built-in middlewares that parse the incoming request. Learn more about them here.
|
||
---
|
||
|
||
# API Middlewares
|
||
|
||
<details open>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/api-routes-middleware">API Routes with middleware</a></li>
|
||
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/api-routes-cors">API Routes with CORS</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
API routes provide built in middlewares which parse the incoming request (`req`). Those middlewares are:
|
||
|
||
- `req.cookies` - An object containing the cookies sent by the request. Defaults to `{}`
|
||
- `req.query` - An object containing the [query string](https://en.wikipedia.org/wiki/Query_string). Defaults to `{}`
|
||
- `req.body` - An object containing the body parsed by `content-type`, or `null` if no body was sent
|
||
|
||
## Custom config
|
||
|
||
Every API route can export a `config` object to change the default configs, which are the following:
|
||
|
||
```js
|
||
export const config = {
|
||
api: {
|
||
bodyParser: {
|
||
sizeLimit: '1mb',
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
The `api` object includes all configs available for API routes.
|
||
|
||
`bodyParser` Enables body parsing, you can disable it if you want to consume it as a `Stream`:
|
||
|
||
```js
|
||
export const config = {
|
||
api: {
|
||
bodyParser: false,
|
||
},
|
||
}
|
||
```
|
||
|
||
`bodyParser.sizeLimit` is the maximum size allowed for the parsed body, in any format supported by [bytes](https://github.com/visionmedia/bytes.js), like so:
|
||
|
||
```js
|
||
export const config = {
|
||
api: {
|
||
bodyParser: {
|
||
sizeLimit: '500kb',
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
`externalResolver` is an explicit flag that tells the server that this route is being handled by an external resolver like _express_ or _connect_. Enabling this option disables warnings for unresolved requests.
|
||
|
||
```js
|
||
export const config = {
|
||
api: {
|
||
externalResolver: true,
|
||
},
|
||
}
|
||
```
|
||
|
||
## Connect/Express middleware support
|
||
|
||
You can also use [Connect](https://github.com/senchalabs/connect) compatible middleware.
|
||
|
||
For example, [configuring CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for your API endpoint can be done leveraging the [cors](https://www.npmjs.com/package/cors) package.
|
||
|
||
First, install `cors`:
|
||
|
||
```bash
|
||
npm i cors
|
||
# or
|
||
yarn add cors
|
||
```
|
||
|
||
Now, let's add `cors` to the API route:
|
||
|
||
```js
|
||
import Cors from 'cors'
|
||
|
||
// Initializing the cors middleware
|
||
const cors = Cors({
|
||
methods: ['GET', 'HEAD'],
|
||
})
|
||
|
||
// Helper method to wait for a middleware to execute before continuing
|
||
// And to throw an error when an error happens in a middleware
|
||
function runMiddleware(req, res, fn) {
|
||
return new Promise((resolve, reject) => {
|
||
fn(req, res, result => {
|
||
if (result instanceof Error) {
|
||
return reject(result)
|
||
}
|
||
|
||
return resolve(result)
|
||
})
|
||
})
|
||
}
|
||
|
||
async function handler(req, res) {
|
||
// Run the middleware
|
||
await runMiddleware(req, res, cors)
|
||
|
||
// Rest of the API logic
|
||
res.json({ message: 'Hello Everyone!' })
|
||
}
|
||
|
||
export default handler
|
||
```
|
||
|
||
> Go to the [API Routes with CORS](https://github.com/zeit/next.js/tree/canary/examples/api-routes-cors) example to see the finished app
|