[내보내번] Next.js docs - API Routes

내보내번(내가 보려고 내가 번역한...) Next.js docs

2021년 4월 11일 기준 Next.js 공식 문서를 번역했다.

※ 영어 전공자도 해외 유학파도 아니기에 번역에는 의역, 오역, 구글 번역이 무수히 많을 수 있으며, 혼자 공식문서를 참조해가며 번역하다 보니 오타도 많을 수 있다. 정확한 내용은 공식문서를 직접 살펴보거나 다른 정보들을 더 찾아보는 것을 추천한다.

(하지만 댓글 피드백도 환영합니다😃 )

Next.js 공식문서 확인하기>>

API Routes: Introduction | Next.js

---

API routes provide a solution to build your API with Next.js.
API 경로는 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/*로 매핑되며 페이지 대신 API 엔드 포인트로 처리된다. 이것들은 서버 측 전용 번들이며 클라이언트 측 번들 크기를 증가시키지 않는다.  

For example, the following API route pages/api/user.js returns a json response with a status code of 200:
예를 들어, 아래의 pages/api/user.js API 경로는 상태 코드 200과 함께 json 응답을 리턴한다: 

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

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:
API 경로가 동작하기 위해서는 함수를 default로 (즉, 요청 핸들러) 내보내야하는데, 그러면 아래의 파라미터들을 받는다. 

• req: An instance of http.IncomingMessage, plus some pre-built middlewares you can see here
• res: An instance of http.ServerResponse, plus some helper functions you can see here
• req: http.IncomingMessage의 인스턴스와 이곳에서 볼 수 있는 일부 미리 빌드된 미들웨어
• res: http.ServerResponse의 인스턴스와 이곳에서 볼 수 있는 일부 헬퍼 함수

To handle different HTTP methods in an API route, you can use req.method in your request handler, like so:
API 경로에서 다른 HTTP 메소드들을 처리하려면 아래와 같이 요청 핸들러 내에서 req.method를 사용할 수 있다:

export default function handler(req, res) {
  if (req.method === 'POST') {
    // Process a POST request
  } else {
    // Handle any other HTTP method
  }
}

To fetch API endpoints, take a look into any of the examples at the start of this section.
API 엔드 포인드를 가져오려면, 이 섹션의 시작하는 부분에 있는 몇 가지 예시를 참조하라. (더보기 참조)

• Basic API Routes
• API Routes with middleware
• API Routes with GraphQL
• API Routes with REST
• API Routes with CORS

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:
새로운 프로젝트를 위해서 API 경로로 전체 API를 빌드할 수 있다. 이미 API가 존재하는 경우, API 경로를 통해서 해당 API로 호출을 전달할 필요가 없다. API 경로의 다른 사용 사례는 다음과 같다:

• Masking the URL of an external service (e.g. /api/secret instead of https://company.com/secret-url)
• Using Environment Variables on the server to securely access external services.
• 외부 서비스의 URL 마스킹 (예. https://company.com/secret-url 대신 /api/secret)
• 서버에서 환경변수를 사용여 안전하게 외부 서비스에 접근

Caveats 주의 사항

• API Routes do not specify CORS headers, meaning they are same-origin only by default. You can customize such behavior by wrapping the request handler with the cors middleware.
• API Routes can't be used with next export
• API 경로는 CORS 헤더를 지정하지 않는다. 즉 기본적으로 동일 출처임을 의미한다. 요청 헤더를 cors 미들웨어로 감싸므로 이러한 동작에 대해 사용자 정의할 수 있다. 
• API 경로는 next export와 함께 사용할 수 없다.