REST API

REST(Representational State Transfer)는 HTTP의 설계 의도를 그대로 활용해 분산 시스템을 만드는 아키텍처 스타일이며, REST API는 이 원칙에 따라 자원(Resource)을 URI(Uniform Resource Identifier)로 식별하고 HTTP 메서드로 행위를 표현하는 API를 말한다. 핵심은 무엇을(자원) URI에, 어떻게(행위) 메서드에 나누어 담는 역할 분리이며, 이 규약 덕분에 클라이언트와 서버가 서로의 내부 구현을 몰라도 일관된 방식으로 소통할 수 있다.

REST의 제약 조건

REST는 로이 필딩(Roy Fielding)의 박사 논문에서 정리된 여섯 가지 제약 조건으로 정의된다. 클라이언트-서버 구조는 화면과 데이터 저장의 관심사를 분리해 독립적인 진화를 가능하게 한다. 무상태(Stateless)는 각 요청이 처리에 필요한 정보를 전부 담아야 하고 서버가 클라이언트의 상태를 세션처럼 기억하지 않아야 한다는 제약으로, 어느 서버가 받아도 같은 결과가 나오므로 수평 확장이 쉬워진다. 캐시 가능(Cacheable)은 응답에 캐시 가능 여부를 명시해 중간 계층이 응답을 재사용할 수 있게 한다. 계층화 시스템(Layered System)은 클라이언트가 최종 서버에 직접 붙었는지 프록시를 거쳤는지 알 필요가 없게 한다. 균일한 인터페이스(Uniform Interface)는 자원 식별, 표현을 통한 조작, 자기 서술적 메시지, HATEOAS(Hypermedia as the Engine of Application State)를 포함하는 가장 REST다운 제약이다. 마지막으로 주문형 코드(Code on Demand)는 선택 사항이다. 실무 API 대부분은 HATEOAS까지 지키지 않으므로, 엄밀한 의미의 REST가 아니라 REST 스타일을 따르는 HTTP API라고 부르는 것이 정확하다는 논점도 알아 둘 만하다.

자원 중심 URI와 메서드 설계

REST 설계의 첫 규칙은 URI에 동사가 아니라 명사를 쓰는 것이다. 행위는 메서드가 표현한다.

좋은 설계
GET    /users            사용자 목록 조회
POST   /users            사용자 생성
GET    /users/42         42번 사용자 조회
PATCH  /users/42         42번 사용자 부분 수정
DELETE /users/42         42번 사용자 삭제
GET    /users/42/orders  42번 사용자의 주문 목록

나쁜 설계
GET  /getUserList
POST /deleteUser?id=42

컬렉션은 복수형 명사로, 개별 자원은 식별자를 붙인 경로로 표현하고, 소속 관계는 계층 경로로 나타낸다. 필터링, 정렬, 페이지네이션(Pagination)은 경로가 아니라 쿼리 문자열로 처리한다. 예를 들어 GET /articles?category=web&sort=latest&page=2처럼 쓴다. 상태 변경 결과는 상태 코드로 알린다. 생성엔 201 Created와 Location 헤더, 본문 없는 성공엔 204 No Content, 잘못된 요청엔 400, 권한 문제엔 401과 403을 구분해 쓰는 것이 표준적인 조합이다. 검색처럼 자원 개념에 딱 맞지 않는 행위는 POST /orders/42/cancel처럼 행위를 하위 자원으로 모델링하는 실용적 절충이 흔히 쓰인다.