RESTful한 API란? 리소스 중심 설계
/users/123 (O) vs /getUser?id=123 (X)| 좋은 예 | 나쁜 예 |
|---|---|
| GET /users | GET /getUsers |
| POST /users | POST /createUser |
| GET /users/123/orders | GET /getUserOrders?id=123 |
/api/v1/users (URL 방식이 가장 보편적)?page=1&limit=20 또는 커서 기반{ error: string, code: string }Q.좋은 REST API 설계 원칙은?
| 원칙 | 내용 |
|---|---|
| 자원은 명사, 행위는 메서드 | /users/1 에 GET, DELETE. /getUser 가 아니다 |
| 복수형 | /users, /orders 로 통일한다 |
| 계층은 경로로 | /users/1/orders |
| 필터와 정렬은 쿼리로 | /orders?status=paid&sort=-created_at |
| 상태 코드를 쓴다 | 성공과 실패를 코드로 구분한다 |
| 응답 형태를 일관되게 | 오류 본문 구조를 전 API 에서 같게 |
| 안전성과 멱등성을 지킨다 | GET 은 변경하지 않는다. PUT 과 DELETE 는 멱등하다 |
일곱 번째가 실무에서 자주 깨집니다. GET 으로 상태를 바꾸면 브라우저의 미리 가져오기나 크롤러가 데이터를 바꿉니다.
그리고 원칙을 다 지키기 어려운 자리가 있습니다. 행위가 자원으로 표현되지 않을 때입니다.
| 상황 | 처리 |
|---|---|
| 비밀번호 재설정 | POST /users/1/password-reset 처럼 하위 자원으로 |
| 여러 자원을 한 번에 | 묶음 전용 엔드포인트를 명시적으로 만든다 |
| 검색 조건이 복잡하다 | POST 로 조건을 본문에 담는 것도 실용적이다 |
흔한 실수: 형식을 완벽하게 맞추려고 억지 경로를 만드는 것. 원칙의 목적은 예측 가능성입니다. 팀 안에서 일관되면 형식적 완벽함보다 낫습니다.
Q.REST vs GraphQL 차이와 선택 기준은?
| 항목 | REST | GraphQL |
|---|---|---|
| 응답 형태 | 서버가 정한다 | 클라이언트가 요청한 필드만 |
| 요청 수 | 여러 자원이면 여러 번 | 한 번에 모아 받는다 |
| 캐싱 | HTTP 캐시를 그대로 쓴다 | 별도 계층이 필요하다 |
| 학습과 도구 | 단순하다 | 스키마와 도구가 필요하다 |
| 과다 조회 | 안 쓰는 필드도 받는다 | 필요한 것만 |
| 서버 부담 | 예측 가능하다 | 무거운 질의가 들어올 수 있다 |
선택 기준입니다.
| 상황 | 선택 |
|---|---|
| 화면마다 필요한 데이터가 크게 다르다 | GraphQL |
| 모바일에서 요청 수와 전송량이 중요하다 | GraphQL |
| 공개 API 로 외부에 제공한다 | REST. 캐싱과 학습 비용에서 유리 |
| 자원 구조가 단순하다 | REST |
| 여러 백엔드를 하나로 모아 준다 | GraphQL |
GraphQL 의 대가를 구체적으로 보면 이렇습니다. 깊게 중첩된 질의가 오면 서버가 수백 번 조회할 수 있어서 질의 복잡도 제한과 묶음 조회가 필수입니다. 그리고 URL 단위 캐싱이 안 되므로 캐싱을 처음부터 설계해야 합니다.
흔한 실수: 과다 조회 문제만 보고 GraphQL 로 옮기는 것. 그 문제는 REST 에서도 필요한 필드만 주는 별도 엔드포인트나 필드 선택 파라미터로 해결됩니다. 화면별 요구가 크게 다를 때 값이 나옵니다.
Q.API 버저닝 전략을 설명해주세요
| 방식 | 예 | 특징 |
|---|---|---|
| 경로 | /v1/users | 가장 흔하다. 눈에 보이고 라우팅이 쉽다 |
| 헤더 | Accept: application/vnd.api.v1+json | URL 이 깨끗하다. 시험과 디버깅이 불편하다 |
| 쿼리 | /users?version=1 | 간단하지만 캐싱에 영향을 준다 |
| 날짜 | API-Version: 2026-08-14 | 클라이언트가 계약 시점을 고정한다 |
더 중요한 것은 언제 버전을 올릴지입니다. 올리면 두 버전을 함께 유지해야 하므로 비용이 큽니다.
| 변경 | 버전을 올리나 |
|---|---|
| 필드 추가 | 아니다. 클라이언트가 무시하면 된다 |
| 선택 파라미터 추가 | 아니다 |
| 필드 삭제나 이름 변경 | 올린다 |
| 타입이나 의미 변경 | 올린다 |
| 필수 파라미터 추가 | 올린다 |
| 오류 코드 추가 | 아니다. 클라이언트가 알 수 없는 코드를 다룰 수 있어야 한다 |
그래서 실무의 요령은 깨지는 변경을 피하는 것입니다. 필드를 지우는 대신 새 필드를 추가하고 옛 필드를 한동안 함께 내주는 방식이면 버전을 올리지 않아도 됩니다.
흔한 실수: 버전만 만들고 폐기 계획을 세우지 않는 것. v1 이 영구히 남아 유지 비용이 계속 듭니다. 도입 시점에 폐기 시점과 사용량 측정을 함께 정해야 합니다.
Q.HATEOAS는 왜 실무에서 잘 쓰이지 않나요?
응답에 다음에 할 수 있는 행동의 링크를 담는 방식입니다. 이론적으로는 클라이언트가 URL 을 몰라도 되지만, 실무에서는 그 이점이 잘 실현되지 않습니다.
| 이유 | 내용 |
|---|---|
| 클라이언트가 링크를 따르지 않는다 | 대부분 경로를 코드에 적어 둔다 |
| 화면 흐름은 어차피 정해져 있다 | 다음에 무엇을 할지 클라이언트가 이미 안다 |
| 응답이 커진다 | 링크가 본문의 상당 부분을 차지한다 |
| 표준이 갈린다 | 링크 표현 형식이 여럿이라 도구가 통일되지 않는다 |
| 개발 비용 | 서버가 상태별로 가능한 행동을 계산해야 한다 |
첫 번째가 근본입니다. 링크로 흐름을 유도하려면 클라이언트가 링크를 해석해 화면을 만들어야 하는데, 실제 앱은 화면을 미리 설계해 두므로 그럴 이유가 없습니다.
그래도 부분적으로 쓰이는 자리는 있습니다.
| 쓰이는 곳 | 내용 |
|---|---|
| 페이지네이션 | 다음 페이지 링크를 응답에 담는 것은 널리 쓰인다 |
| 상태별 가능 행동 | 이 주문을 취소할 수 있는지를 링크 유무로 표현 |
| 비동기 작업 상태 | 작업 조회 URL 을 응답으로 준다 |
흔한 실수: REST 의 필수 요건으로 답하는 것. 원 논문의 성숙도 모델에서는 최상위 단계지만, 업계 대부분의 API 는 그 아래 단계에 머물고 그것으로 잘 작동합니다.
먼저 스스로 답해보고 아래 답변과 견줘보세요. 막히는 부분은 문제로 확인할 수 있어요.
읽었으면 문제로 확인해보세요
API 설계 문제를 풀면 틀린 문제가 자동으로 노트에 쌓입니다. 가입 없이 5문제를 먼저 풀어볼 수도 있어요.