Add use cases for API Routes to documentation. (#22616)

I've seen this confusion come up a few times, specifically [here](https://www.reddit.com/r/nextjs/comments/lsmpon/is_there_a_benefit_to_using_api_when_you_are_only/) for the latest.
This commit is contained in:
Lee Robinson 2021-02-28 19:15:14 -06:00 committed by GitHub
parent 6c59b77702
commit 0a35b578d4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -15,7 +15,7 @@ description: Next.js supports API Routes, which allow you to build your API with
</ul>
</details>
API routes provide a straightforward solution to build your **API** with Next.js.
API routes provide a solution to build your **API** with Next.js.
Any file inside the folder `pages/api` is mapped to `/api/*` and will be treated as an API endpoint instead of a `page`. They are server-side only bundles and won't increase your client-side bundle size.
@ -46,6 +46,13 @@ export default function handler(req, res) {
To fetch API endpoints, take a look into any of the examples at the start of this section.
## Use Cases
For new projects, you can build your entire API with API Routes. If you have an existing API, you do not need to forward calls to the API through an API Route. Some other use cases for API Routes are:
- Masking the URL of an external service (e.g. `/api/secret` instead of `https://company.com/secret-url`)
- Using [Environment Variables](/docs/basic-features/environment-variables.md) on the server to securely access external services.
## 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).