Unverified Commit 0a35b578 authored by Lee Robinson's avatar Lee Robinson Committed by GitHub

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.
parent 6c59b777
...@@ -15,7 +15,7 @@ description: Next.js supports API Routes, which allow you to build your API with ...@@ -15,7 +15,7 @@ description: Next.js supports API Routes, which allow you to build your API with
</ul> </ul>
</details> </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. 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) { ...@@ -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. 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 ## 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 middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment