REST API에서 리소스 URI를 어떻게 명명하고 구조화해야 하는가?

Question

IT Interview Practice · Accepted Answer

리소스 URI는 동작이 아니라 **어떤 "것"으로 향하는 명사 기반 경로**처럼 읽혀야 한다. HTTP method가 이미 동사를 제공하므로, URI는 리소스를 명확하고 일관되게 식별하기만 하면 된다.

## 핵심 규약

- **동사가 아니라 명사를 쓴다.** `GET /users/42` — `GET /getUser?id=42`가 아니다. method(`GET`)가 동사다.
- **collection에는 복수 명사를 쓴다.** `/users`는 collection이고, `/users/42`는 한 멤버다. 어디서나 복수를 유지하면 예측 가능해진다.
- **관계는 중첩(nesting)으로 모델링** — 하되 얕게. `/users/42/orders` = "user 42에 속한 orders".
- **`kebab-case`, 소문자를 쓴다.** `/blog-posts`이지 `/blogPosts`나 `/Blog_Posts`가 아니다.
- **필터링, 정렬, 페이징은 query string에** 두고 path에 두지 않는다: `/users?role=admin&sort=-created_at`.

## 일관된 계층 구조

```text
/users                     collection of users
/users/42                  a single user
/users/42/orders           orders belonging to user 42 (sub-collection)
/users/42/orders/1001      a specific order of that user
/orders/1001               same order, addressable at top level too
```

## 예시

```http
GET /users/42/orders?status=shipped&sort=-created_at&page=2 HTTP/1.1
Accept: application/json
```

한두 단계를 넘는 깊은 중첩은 피하라 — `/users/42/orders/1001/items/5/reviews`는 취약해진다. order가 자기 ID를 갖게 되면 `/orders/1001`을 선호하라. CRUD에 맞지 않는 동작(예: "이메일 보내기")에는 controller 스타일의 sub-resource가 허용된다: `POST /users/42/verify-email`.

## 왜 중요한가

일관된 명명이 API를 직관적으로 느끼게 만든다 — `/users`와 `/users/42`를 본 개발자는 문서를 읽지 않고도 `/products`와 `/products/99`를 올바르게 추측할 수 있다. 면접관은 이를 통해 당신이 **RPC 호출**(`/doThisThing`)이 아니라 **리소스** 관점(REST의 사고방식)으로 생각하는지 가늠한다. 가장 흔한 안티패턴 — path의 동사, 일관성 없는 복수화, 깊이 중첩된 URL — 은 모두 API를 배우고 유지하기 어렵게 만들고, REST의 uniform-interface 제약을 체득하지 못한 개발자임을 드러낸다. 좋은 URI 설계는 관심사도 분리한다: 식별은 path에, 필터링과 페이지네이션은 query string에 — 이것이 캐싱과 라우팅을 깔끔하게 유지한다.

핵심 규약

일관된 계층 구조

예시

왜 중요한가

관련 질문