diff --git a/pages/docs/pages/building-your-application/routing/api-routes.mdx b/pages/docs/pages/building-your-application/routing/api-routes.mdx index 6359926..d328e01 100644 --- a/pages/docs/pages/building-your-application/routing/api-routes.mdx +++ b/pages/docs/pages/building-your-application/routing/api-routes.mdx @@ -3,8 +3,6 @@ title: API Routes description: Next.js supports API Routes, which allow you to build your API without leaving your Next.js app. Learn how it works here. --- -{/* TODO: 번역이 필요합니다. */} - # API Routes
@@ -18,13 +16,13 @@ description: Next.js supports API Routes, which allow you to build your API with
-> **Good to know**: If you are using the App Router, you can use [Server Components](/docs/app/building-your-application/rendering/server-components) or [Route Handlers](/docs/app/building-your-application/routing/route-handlers) instead of API Routes. +> **Good to know** : App Router를 사용하는 경우, API Routes 대신 [Server Components](/docs/app/building-your-application/rendering/server-components) 또는 [Route Handlers](/docs/app/building-your-application/routing/route-handlers) 를 사용할 수 있습니다. -API routes provide a solution to build a **public API** with Next.js. +API routes는 Next.js로 **공용 API** 를 구축할 수 있는 솔루션을 제공합니다. -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. +`pages/api` 폴더 내부의 모든 파일은 `/api/*`로 매핑되어 `page` 대신 API 엔드포인트로 처리됩니다. 이러한 파일들은 서버 사이드 번들로만 존재하며, 클라이언트 사이드 번들 크기를 증가시키지 않습니다. -For example, the following API route returns a JSON response with a status code of `200`: +예를 들어, 다음 API 라우트는 상태 코드 `200`과 함께 JSON 응답을 반환합니다: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -49,10 +47,10 @@ export default function handler(req, res) { > **Good to know**: > -> - API Routes [do not specify CORS headers](https://developer.mozilla.org/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는 기본적으로 **동일 출처** 만 허용하며, [CORS 헤더를 지정하지 않습니다](https://developer.mozilla.org/docs/Web/HTTP/CORS) . 이러한 동작은 [CORS 요청 도우미](https://github.com/vercel/next.js/tree/canary/examples/api-routes-cors) 로 요청 핸들러를 감싸서 사용자 정의할 수 있습니다. -- API Routes can't be used with [static exports](/docs/pages/building-your-application/deploying/static-exports). However, [Route Handlers](/docs/app/building-your-application/routing/route-handlers) in the App Router can. - > - API Routes will be affected by [`pageExtensions` configuration](/docs/pages/api-reference/next-config-js/pageExtensions) in `next.config.js`. +- API Routes는 [정적 내보내기](/docs/pages/building-your-application/deploying/static-exports) 와 함께 사용할 수 없습니다. 그러나 App Router의 [Route Handlers](/docs/app/building-your-application/routing/route-handlers) 를 사용할 수 있습니다. + > - API Routes는 `next.config.js`의 [pageExtensions 설정](/docs/pages/api-reference/next-config-js/pageExtensions) 의 영향을 받습니다. ## Parameters @@ -62,21 +60,21 @@ export default function handler(req: NextApiRequest, res: NextApiResponse) { } ``` -- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage) -- `res`: An instance of [http.ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse) +- `req`: [http.IncomingMessage](https://nodejs.org/api/http.html#class-httpincomingmessage) 인스턴스 +- `res`: [http.ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse) 인스턴스 ## HTTP Methods -To handle different HTTP methods in an API route, you can use `req.method` in your request handler, like so: +API 라우트에서 다양한 HTTP 메서드를 처리하려면 요청 핸들러에서 `req.method`를 사용할 수 있습니다. 예: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' export default function handler(req: NextApiRequest, res: NextApiResponse) { if (req.method === 'POST') { - // Process a POST request + // POST 요청 처리 } else { - // Handle any other HTTP method + // 다른 HTTP 메서드 처리 } } ``` @@ -84,24 +82,24 @@ export default function handler(req: NextApiRequest, res: NextApiResponse) { ```js filename="pages/api/hello.js" switcher export default function handler(req, res) { if (req.method === 'POST') { - // Process a POST request + // POST 요청 처리 } else { - // Handle any other HTTP method + // 다른 HTTP 메서드 처리 } } ``` ## Request Helpers -API Routes provide built-in request helpers which parse the incoming request (`req`): +API Routes는 들어오는 요청(`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 `{}` -- `req.body` - An object containing the body parsed by `content-type`, or `null` if no body was sent +- `req.cookies` - 요청에 의해 전송된 쿠키를 포함하는 객체. 기본값은 `{}` +- `req.query` - [쿼리 문자열](https://en.wikipedia.org/wiki/Query_string) 을 포함하는 객체. 기본값은 `{}` +- `req.body` - `content-type`에 따라 구문 분석된 body를 포함하는 객체, body가 전송되지 않은 경우 `null` ### Custom config -Every API Route can export a `config` object to change the default configuration, which is the following: +모든 API 라우트는 기본 설정을 변경하기 위해 `config` 객체를 내보낼 수 있습니다. 기본 설정은 다음과 같습니다: ```js export const config = { @@ -110,14 +108,14 @@ export const config = { sizeLimit: '1mb', }, }, - // Specifies the maximum allowed duration for this function to execute (in seconds) + // 이 함수가 실행되는 최대 허용 시간을 지정함 (초 단위) maxDuration: 5, } ``` -`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`. +`bodyParser`는 자동으로 활성화됩니다. body를 `Stream`으로 소비하거나 [raw-body](https://www.npmjs.com/package/raw-body) 로 소비하려면 이를 `false`로 설정할 수 있습니다. -One use case for disabling the automatic `bodyParsing` is to allow you to verify the raw body of a **webhook** request, for example [from GitHub](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks#validating-payloads-from-github). +자동 `bodyParsing`을 비활성화하는 한 가지 사용 사례는 예를 들어 [GitHub](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks#validating-payloads-from-github) **웹훅** 요청의 원본 body를 확인할 수 있도록 하는 것입니다. ```js export const config = { @@ -127,7 +125,7 @@ export const config = { } ``` -`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: +`bodyParser.sizeLimit`은 [bytes](https://github.com/visionmedia/bytes.js) 가 지원하는 형식으로 구문 분석된 body의 최대 크기입니다. 예를 들어: ```js export const config = { @@ -139,7 +137,7 @@ export const config = { } ``` -`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. +`externalResolver`는 이 라우트가 _express_ 또는 *connect*와 같은 외부 리졸버에 의해 처리되고 있음을 서버에 명시적으로 알리는 플래그입니다. 이 옵션을 활성화하면 해결되지 않은 요청에 대한 경고가 비활성화됩니다. ```js export const config = { @@ -149,9 +147,9 @@ export const config = { } ``` -`responseLimit` is automatically enabled, warning when an API Routes' response body is over 4MB. +`responseLimit`는 자동으로 활성화되며, API 라우트의 응답 body가 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`. +서버리스 환경에서 Next.js를 사용하지 않고, CDN이나 전용 미디어 호스트를 사용하지 않는 경우의 성능 영향을 이해하는 경우, 이 제한을 `false`로 설정할 수 있습니다. ```js export const config = { @@ -161,8 +159,8 @@ export const config = { } ``` -`responseLimit` can also take the number of bytes or any string format supported by `bytes`, for example `1000`, `'500kb'` or `'3mb'`. -This value will be the maximum response size before a warning is displayed. Default is 4MB. (see above) +`responseLimit`은 또한 `bytes`에서 지원하는 형식의 바이트 수 또는 문자열 형식을 취할 수 있습니다. 예를 들어 `1000`, `'500kb'` 또는 `'3mb'` 등이 있습니다. +이 값은 경고가 표시되기 전에 응답 크기의 최대값입니다. 기본값은 4MB입니다. (위 참조) ```js export const config = { @@ -174,21 +172,21 @@ export const config = { ## 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. +[서버 응답 객체](https://nodejs.org/api/http.html#http_class_http_serverresponse) (종종 `res`로 약칭됨)에는 개발자 경험을 개선하고 새로운 API 엔드포인트를 생성하는 속도를 높이기 위한 Express.js와 유사한 도우미 메서드 세트가 포함되어 있습니다. -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/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/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation) using `getStaticProps`. `urlPath` must be a `string`. +- `res.status(code)` - 상태 코드를 설정하는 함수. `code`는 유효한 [HTTP 상태 코드](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) 여야 합니다 +- `res.json(body)` - JSON 응답을 보냅니다. `body`는 [직렬화 가능한 객체](https://developer.mozilla.org/docs/Glossary/Serialization) 여야 합니다 +- `res.send(body)` - HTTP 응답을 보냅니다. `body`는 `string`, `object` 또는 `Buffer`일 수 있음 +- `res.redirect([status,] path)` - 지정된 경로 또는 URL로 리디렉션합니다. `status`는 유효한 [HTTP 상태 코드](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) 여야 하며, 지정되지 않으면 기본값은 "307" "임시 리디렉션"입니다. +- `res.revalidate(urlPath)` - `getStaticProps`를 사용하여 [페이지를 필요에 따라 재검증](/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#on-demand-revalidation) 합니다. `urlPath`는 `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: +다음 예제는 응답의 상태 코드를 `200` (`OK`)으로 설정하고 `Hello from Next.js!` 값의 `message` 프로퍼티와 함께 JSON 응답을 반환합니다: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -213,10 +211,10 @@ export default function handler(req, res) { ### 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/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. +클라이언트에 응답을 보낼 때 JSON 응답을 보낼 수 있습니다. 이는 [직렬화 가능한 객체](https://developer.mozilla.org/docs/Glossary/Serialization) 여야 합니다. +실제 애플리케이션에서는 요청된 엔드포인트의 결과에 따라 요청의 상태를 클라이언트에 알리고자 할 수 있습니다. -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: +다음 예제는 상태 코드 `200` (`OK`)와 비동기 작업의 결과를 포함한 JSON 응답을 보냅니다. 오류가 발생할 수 있는 상황을 처리하기 위해 try catch 블록에 포함되어 있으며, 적절한 상태 코드와 함께 잡힌 오류 메시지를 클라이언트에 다시 보냅니다: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -229,7 +227,7 @@ export default async function handler( const result = await someAsyncOperation() res.status(200).json({ result }) } catch (err) { - res.status(500).json({ error: 'failed to load data' }) + res.status(500).json({ error: '데이터를 불러오는 데 실패했습니다.' }) } } ``` @@ -240,16 +238,16 @@ export default async function handler(req, res) { const result = await someAsyncOperation() res.status(200).json({ result }) } catch (err) { - res.status(500).json({ error: 'failed to load data' }) + res.status(500).json({ error: '데이터를 불러오는 데 실패했습니다.' }) } } ``` ### 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`. +HTTP 응답을 보내는 것은 JSON 응답을 보내는 것과 동일하게 작동합니다. 유일한 차이점은 응답 body가 `string`, `object` 또는 `Buffer`일 수 있다는 것입니다. -The following example sends a HTTP response with the status code `200` (`OK`) and the result of the async operation. +다음 예제는 상태 코드 `200` (`OK`)와 비동기 작업의 결과를 포함한 HTTP 응답을 보냅니다. ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -262,7 +260,7 @@ export default async function handler( const result = await someAsyncOperation() res.status(200).send({ result }) } catch (err) { - res.status(500).send({ error: 'failed to fetch data' }) + res.status(500).send({ error: '데이터를 가져오는 데 실패했습니다' }) } } ``` @@ -273,16 +271,16 @@ export default async function handler(req, res) { const result = await someAsyncOperation() res.status(200).send({ result }) } catch (err) { - res.status(500).send({ error: 'failed to fetch data' }) + res.status(500).send({ error: '데이터를 가져오는 데 실패했습니다' }) } } ``` ### 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. +양식을 예로 들어, 양식을 제출한 후 클라이언트를 지정된 경로 또는 URL로 리디렉션하고자 할 수 있습니다. -The following example redirects the client to the `/` path if the form is successfully submitted: +다음 예제는 양식이 성공적으로 제출되면 클라이언트를 `/` 경로로 리디렉션합니다: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -297,7 +295,7 @@ export default async function handler( await handleFormInputAsync({ name, message }) res.redirect(307, '/') } catch (err) { - res.status(500).send({ error: 'Failed to fetch data' }) + res.status(500).send({ error: '데이터를 가져오는 데 실패했습니다' }) } } ``` @@ -310,14 +308,14 @@ export default async function handler(req, res) { await handleFormInputAsync({ name, message }) res.redirect(307, '/') } catch (err) { - res.status(500).send({ error: 'failed to fetch data' }) + res.status(500).send({ error: '데이터를 가져오는 데 실패했습니다' }) } } ``` ### Adding TypeScript types -You can make your API Routes more type-safe by importing the `NextApiRequest` and `NextApiResponse` types from `next`, in addition to those, you can also type your response data: +`NextApiRequest` 및 `NextApiResponse` 타입을 `next`에서 가져와 API Routes를 더 타입 안정적으로 만들 수 있습니다. 추가로, 응답 데이터도 타입 지정할 수 있습니다: ```ts import type { NextApiRequest, NextApiResponse } from 'next' @@ -334,11 +332,11 @@ export default function handler( } ``` -> **Good to know**: 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. +> **Good to know** : `NextApiRequest`의 body는 `any`입니다. 이는 클라이언트가 임의의 페이로드를 포함할 수 있기 때문입니다. body를 사용하기 전에 런타임에서 body의 타입/형태를 검증해야 합니다. ## Dynamic API Routes -API Routes support [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes), and follow the same file naming rules used for `pages/`. +API Routes는 [dynamic routes](/docs/pages/building-your-application/routing/dynamic-routes) 를 지원하며, `pages/`에 사용된 파일 명명 규칙을 따릅니다. ```ts filename="pages/api/post/[pid].ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -356,29 +354,29 @@ export default function handler(req, res) { } ``` -Now, a request to `/api/post/abc` will respond with the text: `Post: abc`. +이제 `/api/post/abc`로의 요청은 `Post: abc`라는 텍스트로 응답합니다. ### Catch all API routes -API Routes can be extended to catch all paths by adding three dots (`...`) inside the brackets. For example: +API Routes는 괄호 안에 세 개의 점(`...`)을 추가하여 모든 경로를 포착하도록 확장할 수 있습니다. 예: -- `pages/api/post/[...slug].js` matches `/api/post/a`, but also `/api/post/a/b`, `/api/post/a/b/c` and so on. +- `pages/api/post/[...slug].js`는 `/api/post/a`와 일치하지만, `/api/post/a/b`, `/api/post/a/b/c` 등과도 일치합니다. -> **Good to know**: You can use names other than `slug`, such as: `[...param]` +> **Good to know** : `slug` 외에도 `[...param]`과 같은 이름을 사용할 수 있습니다. -Matched parameters will be sent as a query parameter (`slug` in the example) to the page, and it will always be an array, so, the path `/api/post/a` will have the following `query` object: +일치하는 매개변수는 페이지에 쿼리 매개변수로 전송되며(예제에서는 `slug`), 항상 배열 형태로 전송됩니다. 따라서 `/api/post/a` 경로는 다음과 같은 `query` 객체를 가집니다: ```json { "slug": ["a"] } ``` -And in the case of `/api/post/a/b`, and any other matching path, new parameters will be added to the array, like so: +그리고 `/api/post/a/b` 및 다른 일치하는 경로의 경우, 새로운 매개변수가 배열에 추가됩니다. 예: ```json { "slug": ["a", "b"] } ``` -For example: +예를 들어: ```ts filename="pages/api/post/[...slug].ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -396,33 +394,33 @@ export default function handler(req, res) { } ``` -Now, a request to `/api/post/a/b/c` will respond with the text: `Post: a, b, c`. +이제 `/api/post/a/b/c`로의 요청은 `Post: a, b, c`라는 텍스트로 응답합니다. ### Optional catch all API routes -Catch all routes can be made optional by including the parameter in double brackets (`[[...slug]]`). +모든 경로 포착 라우트를 선택적 포착 라우트로 만들려면 매개변수를 이중 괄호(`[[...slug]]`)에 포함합니다. -For example, `pages/api/post/[[...slug]].js` will match `/api/post`, `/api/post/a`, `/api/post/a/b`, and so on. +예를 들어, `pages/api/post/[[...slug]].js`는 `/api/post`, `/api/post/a`, `/api/post/a/b` 등과 일치합니다. -The main difference between catch all and optional catch all routes is that with optional, the route without the parameter is also matched (`/api/post` in the example above). +모든 경로 포착 라우트와 선택적 모든 경로 포착 라우트의 주요 차이점은 매개변수 없이도 경로가 일치한다는 점입니다(위 예제에서는 `/api/post`). -The `query` objects are as follows: +`query` 객체는 다음과 같습니다: ```json -{ } // GET `/api/post` (empty object) -{ "slug": ["a"] } // `GET /api/post/a` (single-element array) -{ "slug": ["a", "b"] } // `GET /api/post/a/b` (multi-element array) +{ } // `GET /api/post` (빈 객체) +{ "slug": ["a"] } // `GET /api/post/a` (단일 요소 배열) +{ "slug": ["a", "b"] } // `GET /api/post/a/b` (다중 요소 배열) ``` ### Caveats -- Predefined API routes take precedence over dynamic API routes, and dynamic API routes over catch all API routes. Take a look at the following examples: - - `pages/api/post/create.js` - Will match `/api/post/create` - - `pages/api/post/[pid].js` - Will match `/api/post/1`, `/api/post/abc`, etc. But not `/api/post/create` - - `pages/api/post/[...slug].js` - Will match `/api/post/1/2`, `/api/post/a/b/c`, etc. But not `/api/post/create`, `/api/post/abc` +- 미리 정의된 API 라우트는 동적 API 라우트보다 우선하며, 동적 API 라우트는 모든 경로 포착 API 라우트보다 우선합니다. 다음 예제를 참조하세요: +- `pages/api/post/create.js` - `/api/post/create`와 일치합니다. +- `pages/api/post/[pid].js` - `/api/post/1`, `/api/post/abc` 등과 일치하지만 `/api/post/create`와는 일치하지 않습니다. +- `pages/api/post/[...slug].js` - `/api/post/1/2`, `/api/post/a/b/c` 등과 일치하지만 `/api/post/create`, `/api/post/abc`와는 일치하지 않습니다. ## Edge API Routes -If you would like to use API Routes with the Edge Runtime, we recommend incrementally adopting the App Router and using [Route Handlers](/docs/app/building-your-application/routing/route-handlers) instead. +API Routes를 Edge Runtime과 함께 사용하고자 하는 경우, 점진적으로 App Router를 도입하고 [Route Handlers](/docs/app/building-your-application/routing/route-handlers) 를 사용하는 것을 권장합니다. -The Route Handlers function signature is isomorphic, meaning you can use the same function for both Edge and Node.js runtimes. +Route Handlers 함수 시그니처는 isomorphic으로, Edge와 Node.js 런타임 모두에 동일한 함수를 사용할 수 있습니다.