From 5d93753bc304fa65acb11e534126d37ce1d1ebe1 Mon Sep 17 00:00:00 2001
From: Lee Robinson <me@leerob.io>
Date: Mon, 8 Aug 2022 21:02:14 -0500
Subject: [PATCH] API Routes Request Helpers docs. (#39407)

Renames Middleware to Request Helpers to be both more accurate and also less confusing since Middleware is a separate feature of Next.js now.
---
 docs/api-routes/introduction.md               | 11 ++--
 ...{api-middlewares.md => request-helpers.md} | 65 ++-----------------
 docs/api-routes/response-helpers.md           |  2 +-
 docs/manifest.json                            |  9 ++-
 errors/invalid-page-config.md                 |  2 +-
 5 files changed, 22 insertions(+), 67 deletions(-)
 rename docs/api-routes/{api-middlewares.md => request-helpers.md} (70%)

diff --git a/docs/api-routes/introduction.md b/docs/api-routes/introduction.md
index e771303a108a..7efb489781cb 100644
--- a/docs/api-routes/introduction.md
+++ b/docs/api-routes/introduction.md
@@ -8,7 +8,6 @@ description: Next.js supports API Routes, which allow you to build your API with
   <summary><b>Examples</b></summary>
   <ul>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes">Basic API Routes</a></li>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware">API Routes with middleware</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-graphql">API Routes with GraphQL</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-rest">API Routes with REST</a></li>
     <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors">API Routes with CORS</a></li>
@@ -31,7 +30,7 @@ export default function handler(req, res) {
 
 For an API route to work, you need to export a function as default (a.k.a **request handler**), which then receives the following parameters:
 
-- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage), plus some [pre-built middlewares](/docs/api-routes/api-middlewares.md)
+- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage), plus some [pre-built middlewares](/docs/api-routes/request-helpers.md)
 - `res`: An instance of [http.ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse), plus some [helper functions](/docs/api-routes/response-helpers.md)
 
 To handle different HTTP methods in an API route, you can use `req.method` in your request handler, like so:
@@ -57,7 +56,7 @@ For new projects, you can build your entire API with API Routes. If you have an
 
 ## Caveats
 
-- API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [CORS middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support).
+- API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [CORS request helpers](https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors).
 - API Routes can't be used with [`next export`](/docs/advanced-features/static-html-export.md)
 
 ## Related
@@ -65,9 +64,9 @@ For new projects, you can build your entire API with API Routes. If you have an
 For more information on what to do next, we recommend the following sections:
 
 <div class="card">
-  <a href="/docs/api-routes/api-middlewares.md">
-    <b>API Middlewares:</b>
-    <small>learn about the built-in middlewares for the request.</small>
+  <a href="/docs/api-routes/request-helpers.md">
+    <b>API Routes Request Helpers:</b>
+    <small>learn about the built-in helpers for the request.</small>
   </a>
 </div>
 
diff --git a/docs/api-routes/api-middlewares.md b/docs/api-routes/request-helpers.md
similarity index 70%
rename from docs/api-routes/api-middlewares.md
rename to docs/api-routes/request-helpers.md
index d564bbdbce61..28be26d66cf4 100644
--- a/docs/api-routes/api-middlewares.md
+++ b/docs/api-routes/request-helpers.md
@@ -1,18 +1,18 @@
 ---
-description: API Routes provide built-in middlewares that parse the incoming request. Learn more about them here.
+description: API Routes provide built-in request helpers that parse the incoming request. Learn more about them here.
 ---
 
-# API Middlewares
+# API Routes Request Helpers
 
 <details open>
   <summary><b>Examples</b></summary>
   <ul>
-    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware">API Routes with middleware</a></li>
+    <li><a href="https://github.com/vercel/next.js/tree/canary/examples/api-routes-middleware">API Routes Request Helpers</a></li>
     <li><a href="https://github.com/vercel/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:
+API Routes provide built-in request helpers which parse the incoming request (`req`):
 
 - `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 `{}`
@@ -20,7 +20,7 @@ API routes provide built in middlewares which parse the incoming reques
 
 ## Custom config
 
-Every API route can export a `config` object to change the default configs, which are the following:
+Every API Route can export a `config` object to change the default configuration, which is the following:
 
 ```js
 export const config = {
@@ -32,7 +32,7 @@ export const config = {
 }
 ```
 
-The `api` object includes all configs available for API routes.
+The `api` object includes all config options available for API Routes.
 
 `bodyParser` is automatically enabled. If you want to consume the body as a `Stream` or with [`raw-body`](https://www.npmjs.com/package/raw-body), you can set this to `false`.
 
@@ -68,7 +68,7 @@ export const config = {
 }
 ```
 
-`responseLimit` is automatically enabled, warning when an API routes' response body is over 4MB.
+`responseLimit` is automatically enabled, warning when an API Routes' response body is over 4MB.
 
 If you are not using Next.js in a serverless environment, and understand the performance implications of not using a CDN or dedicated media host, you can set this limit to `false`.
 
@@ -91,57 +91,6 @@ export const config = {
 }
 ```
 
-## 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/vercel/next.js/tree/canary/examples/api-routes-cors) example to see the finished app.
-
 ## Extending the `req`/`res` objects with TypeScript
 
 For better type-safety, it is not recommended to extend the `req` and `res` objects. Instead, use functions to work with them:
diff --git a/docs/api-routes/response-helpers.md b/docs/api-routes/response-helpers.md
index 1fbf9f4913ad..58477cf274cf 100644
--- a/docs/api-routes/response-helpers.md
+++ b/docs/api-routes/response-helpers.md
@@ -2,7 +2,7 @@
 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.
 ---
 
-# Response Helpers
+# 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.
 
diff --git a/docs/manifest.json b/docs/manifest.json
index 5f890a704c79..453661860c83 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -127,6 +127,13 @@
         {
           "title": "API Routes",
           "routes": [
+            {
+              "path": "/docs/api-routes/api-middlewares",
+              "redirect": {
+                "destination": "/docs/api-routes/request-helpers",
+                "permanent": true
+              }
+            },
             {
               "title": "Introduction",
               "path": "/docs/api-routes/introduction.md"
@@ -137,7 +144,7 @@
             },
             {
               "title": "API Middlewares",
-              "path": "/docs/api-routes/api-middlewares.md"
+              "path": "/docs/api-routes/request-helpers.md"
             },
             {
               "title": "Response Helpers",
diff --git a/errors/invalid-page-config.md b/errors/invalid-page-config.md
index 6d24391d2ea4..c9feeb38dbaa 100644
--- a/errors/invalid-page-config.md
+++ b/errors/invalid-page-config.md
@@ -115,5 +115,5 @@ export const config = {}
 ### Useful Links
 
 - [Enabling AMP Support](https://nextjs.org/docs/advanced-features/amp-support/introduction)
-- [API Middlewares](https://nextjs.org/docs/api-routes/api-middlewares)
+- [API Routes Request Helpers](https://nextjs.org/docs/api-routes/request-helpers)
 - [Switchable Runtime](https://nextjs.org/docs/advanced-features/react-18/switchable-runtime)