Next.js API Routes
[공지사항] 푸샤 깃허브 블로그 업데이트 사항
API Routes란?
API(Application Programming Interface)는 API는 컴퓨터나 컴퓨터 프로그램 사이의 연결이다. 일종의 소프트웨어 인터페이스이며 다른 종류의 소프트웨어에 서비스를 제공한다. 이러한 연결이나 인터페이스를 빌드하거나 사용하는 방법을 기술하는 문서나 표준은 API 사양으로 부른다.쉽게 말해 사용자와 상품 개발자 사이를 이어주는사용설명서라고 보면 된다. 인터페이스는 컴퓨터나 기계간의 정보 교환하기 위한 수단이나 방법을 의미한다.Routes는경로라는 의미로써 여기서는URL 경로라고 생각하면 된다.
예시
API routes 는 당신의 Next.js의 API 빌드 솔루션(해결책)을 제공합니다.
pages/api 폴더에 있는 모든 파일들은 /api/\* 매핑되어, page가 아닌 API Endpoint 로 처리됩니다. 해당 bundles(번들들은) 오직 server-side 에서만 번들되어, client-side 번들 사이즈를 증가시키지 않습니다.
에를 들어, pages/api/user.js 해당 API route는 200 상태 코드인 json 반환시킵니다.
export default function handler(req, res) {
res.status(200).json({ name: "John Doe" });
}
API 라우터가 작동하기 위해서는 default 함수(request handler 라 불리는)를 export 해야하며, 아래와 같은 파라미터를 가집니다.
req: http.incomingMessage 인스턴스이다. 미들웨어로 적용하고 싶다면 Api-middlewares를 살펴보세요.res: http.ServerResponse 인스턴스이다. Response helper 함수 를 살펴보면 더 좋습니다.
서로 다른 HTTP 메서드를 API 라우터에서 다루기 위해 req.method 를 request handler 안에서 사용할 수 있습니다.
export default function handler(req, res) {
if (req.method === "POST") {
// POST request 처리
} else {
// 그 외의 다른 HTTP method
}
}
API 엔드포인트 fetch하기 위해서는 이 페이지의 상단 시작 부분에 있는 예제를 참조하세요.
사용 사례
새로운 프로젝트인 경우, API 라우터를 사용해 전체 API 를 빌드할 수 있습니다. 만약 API 가 이미 존재한다면, API 라우터로 API 를 호출할 필요는 없습니다. API 라우터의 다른 사례는 다음과 같습니다.
- 외부 서비스의 URL 마스킹 할 수 있습니다.(https://domain.com/secret-url -> /api/secret)
- 서버의 환경변수를 사용해 외부 서비스에 안정적으로 접근할 수 있습니다.
주의사항
- API 라우터는 CORS 헤더를 지정하지 않습니다. 이는 기본적으로 오직
same-origin만 있음을 뜻합니다. 동작(behavior) 커스터마이징하고 싶다면 CORS 미들웨어 를 request handler 에 래핑하면 됩니다. - API 라우터는
next export에서 사용할 수 없습니다.
Dynamic API Routes
예시
API routes는 dynamic routes 지원하고,동일한 파일 명명 규칙을 pages에 따릅니다.
예를 들어 API route(경로) pages/api/post/[pid].js 에는 다음 코드가 있습니다.
export default function handler(req, res) {
const { pid } = req.query;
res.end(`Post: ${pid}`);
}
이제, /api/post/abc에 대한 요청에 Post: abc라는 텍스트가 응답할 것입니다.
Index routes 와 Dynamic API routes
매우 일반적인 RESTful 패턴은 다음과 같이 경로를 설정합니다:
GET api/posts- 페이지가 매겨진 게시물 목록을 얻습니다.GET api/posts/12345- 게시물 ID 12345를 얻습니다.
이를 두 가지 방법으로 모델링할 수 있습니다.
-
옵션 1:
/api/posts.js/api/posts/[postId].js
-
옵션 2:
/api/posts/index.js/api/posts/[postId].js둘 다 같습니다. 세번째 옵션으로 오직/api/posts/[postId].js만 쓰는 것은 유효하지 않은데, 왜냐하면 Dynamic Routes(모든 routes 포함 - 아래 참조)에는undefined상태와GET api/posts는 어떠한 상황에서도/api/posts/[postId].js매칭 시켜주지 않기 때문입니다.
모든 API routes 읽기(catch)
API routes는 대괄호 안에 세 개의 점(...)을 추가하여 모든 경로를 읽을 수 있도록 확장할 수 있습니다. 예:
pages/api/post/[...slug].js는/api/post/a뿐만 아니라/api/post/a/b,/api/post/a/b/c등등 매칭이 됩니다.
참조 : slug 이외의 이름을 [...param]와 같이 지을 수 있습니다.
일치하는 매개변수(parameter)는 query parameter(예시에 있는 slug)로 페이지에 전송되며, 항상 배열이 되며, 경로(path) /api/post/a에는 다음 query 객체(object)가 있습니다.
{ "slug": ["a"] }
/api/post/a/b 경우, 그리고 다른 매칭되는 경로는, 새로운 parameter들이 추가되어 다음과 같은 배열(array)이 됩니다:
{ "slug": ["a", "b"] }
pages/api/post/[...slug].js의 API route는 다음과 같습니다.
export default function handler(req, res) {
const { slug } = req.query;
res.end(`Post: ${slug.join(", ")}`);
}
이제, api/post/a/b/c에 대한 요청(request)는 Post: a, b, c의 text로 응답(response)될 것입니다.
댓글남기기