REST API 6가지 원칙과 URI 네임 컨벤션

REST (REpresentational State Transfer)

웹에서 데이터를 주고받을 때 모두가 이해하기 쉽게 규칙을 통일하자고 만든 설계 가이드라인

이 가이드라인을 잘 지킨 API를 RESTful하다고 부른다

REST API 6가지 핵심 원칙

1. 인터페이스 일관성 (Uniform Interface)

시스템 내부의 자원들을 API 소비자가 사용할 수 있도록 일관된 규칙에 따라 공개해야 한다

• 단일 논리적 URI: 시스템의 자원은 오직 하나의 논리적 URI를 가진다
• 적절한 크기 유지: 단일 자원이 모든 정보를 다 담고 있을 정도로 크면 안된다
• HATEOAS (관련 링크 제공): 자원의 상태 표현에는 관련된 다른 정보를 가져올 수 있는 상대 URI 링크가 포함되어야 한다 (웹 페이지의 하이퍼링크와 유사)
• 일관된 규약: 명명 규칙, 데이터 형식(XML/JSON), HTTP 메서드(GET, POST 등) 사용 방식이 시스템 전체에서 동일해야 한다

2. 클라이언트-서버 구조 (Client-Server)

클라이언트와 서버는 서로에게 의존하지 않고 독립적으로 개발 및 교체할 수 있어야 한다

• 클라이언트는 서버의 내부 복잡성을 알 필요 없이 자원의 URI만 알면 된다
• 약속된 인터페이스만 변경되지 않는다면, 한쪽을 완전히 수정하더라도 다른 쪽에 영향을 주지 않아야 한다

3. 무상태성 (Stateless)

서버는 클라이언트의 상태(세션, 이전 요청 기록 등)를 전혀 저장하지 않습니다. 모든 요청은 이전 요청과 무관하게 독립적이고 새로운 것으로 취급된다

• 서버가 이전 로그인 상태를 기억하지 않으므로, 클라이언트가 매 요청마다 인증 정보와 필요한 모든 데이터를 함께 보내야 한다
• 애플리케이션의 상태 관리 책임은 전적으로 클라이언트에게 있다

4. 캐시 처리 가능 (Cacheable)

웹 페이지를 캐싱하여 빠르게 읽어오는 것처럼, API 응답 데이터도 캐싱이 가능해야 한다

• 응답은 스스로가 캐시 가능한 데이터인지 명시해야 한다
• 캐싱을 통해 네트워크 비용을 줄이고, 서버의 부하를 낮춰 전체적인 시스템 성능과 확장성을 크게 높일 수 있다

5. 계층화된 시스템 (Layered System)

REST는 시스템을 다중 계층으로 분리하는 것을 허용한다. (예: API 서버, DB 서버, 인증 서버 분리)

• 클라이언트는 자신이 최종 서버와 직접 통신하는지, 아니면 중간 계층(로드 밸런서, 프록시 서버 등)과 통신하는지 알 수 없고, 알 필요도 없다

6. 주문형 코드 (Code on Demand)

대부분의 API는 XML이나 JSON 형태의 정적인 데이터를 반환하지만, 필요하다면 클라이언트에서 실행할 수 있는 '코드' 자체를 반환할 수도 있다

• 예: 클라이언트 API 호출 시 UI 위젯을 렌더링하는 자바스크립트 실행 코드를 전달
• 6가지 원칙 중 유일하게 필수가 아닌 선택(Optional) 사항
  

REST API URI Naming Conventions

1. 모든 것은 '자원'이며 명사로 표현한다

문서, 이미지, 사람 등 이름을 붙일 수 있는 모든 개념이 자원이 될 수 있다.

• 단일 자원 (Document/Singleton) : 객체 인스턴스나 데이터베이스의 레코드 하나를 의미한다 예) /users/{id}
• 컬렉션 자원 (Collection) : 서버가 관리하는 자원들의 디렉토리로 항상 복수형 명사를 사용한다 예) /users
• 하위 컬렉션 (Sub-collection) : 특정 자원에 속한 또 다른 자원 목록이다 예) /users/{id}/accounts

2. 행위는 URI가 아닌 HTTP 메서드로 표현한다

URI는 오직 어떤 자원인지 식별하는 데만 사용해야 하며, 자원에 대한 CRUD 행위를 URI에 포함해서는 안된다

• 잘못된 예시 /books/create /users/{id}/delete
• 올바른 예시 POST /books DELETE /users/{id}

3. 일관성 있고 가독성 높은 URI 포맷팅 규칙

• 계층 관계는 /로 표현
• URI 마지막에 의미없는 /를 붙이지 않는다
• 하이픈(-) 사용, 언더스코어(_) 사용 금지
• 소문자 사용
• 파일 확장자 제거

4. 필터링, 정렬, 검색은 쿼리 파라미터(?) 활용

특정 조건에 맞는 자원만 가져오고 싶을 때마가 새로운 URI를 만드는 것이 아닌 컬렉션 자원의 URI에 쿼리 파라미터를 조합 예) GET /managed-devices?region=USA&brand=XYZ&sort=installation-date

참고문서

REST Architectural Constraints

URI Naming Convention