REST 리소스 명명 가이드

REST 리소스 명명 가이드

• REST API 설계 시 리소스 명명 관련 참고 자료
• 공식 가이드가 아닌 Best Practices로 참고 자료로만 사용

리소스(Resource)란?

• REST에서 기본 데이터 표현을 리소스라고 함
• REST에서 정보의 핵심 추상화는 리소스이며, 이름을 지정할 수 있는 모든 정보는 리소스가 될 수 있음
  • 예: 문서 또는 이미지, 시간 서비스, 기타 리소스 모음, 가상이 아닌 개체
• 하이퍼텍스트 참조의 대상이 될 수 있는 모든 개념은 리소스의 정의에 맞아야 함
• 리소스는 특정 시점의 매핑에 해당하는 엔터티가 아니라 엔터티 집합에 대한 개념적 매핑

단일 및 컬렉션 리소스

• 리소스는 단일 또는 컬렉션일 수 있음
• 컬렉션 리소스 예: customers
  • URI: /customers
• 단일 리소스 예: customer
  • URI: /customers/{customerId}

컬렉션 및 하위 컬렉션 리소스

• 리소스에는 하위 컬렉션 리소스도 포함될 수 있음
• 예시 1: customer의 하위 컬렉션 리소스 accounts
  • URN: /customers/{customerId}/accounts
• 예시 2: accounts의 단일 리소스 account
  • URN: /customers/{customerId}/accounts/{accountId}

URI(Uniform Resource Identifier)

• REST API는 URI를 사용하여 리소스를 처리
• REST API 설계자는 REST API의 리소스 모델을 API의 잠재적 클라이언트에 전달하는 URI를 만들어야 함
• 리소스 이름을 잘 지정하면 API가 직관적이고 사용하기 쉬움, 반대로 제대로 수행되지 않으면 API 사용이 어렵고 이해하기 어려움
• 균일한 인터페이스의 제약은 URI와 HTTP 메서드(동작)를 조합으로 부분적으로 해결되고 표준 및 규칙에 따라 사용

Best Practices

명사를 사용하여 자원을 나태냄

• URI는 사물(명사)인 리소스를 참조해야 함
• 예 

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}

• 더 명확하게 하기 위해 리소스 원형을 4가지 범주로 나눔
  • 문서(document)
  • 컬렉션(collections)
  • 저장소(store)
  • 컨트롤러(controller)

문서(document)

• 개체 인스턴스 또는 데이터베이스 레코드와 유사한 단일 개념
• REST에서는 리소스 컬렉션 내의 단일 리소스로 볼 수 있음
• 일반적으로 값이 있는 필드와 다른 관련 리소스에 대한 링크가 모두 포함
• 문서 리소스 원형을 나태 내기 위해 '단수' 이름을 사용
  • 예: http://api.example.com/user-management/users/{id}

컬렉션(collections)

• 리소스의 서버 관리 디렉터리
• 클라이언트는 컬렉션에 추가할 새로운 리소스를 제안할 수 있지만 만들지 여부를 선택하는 것은 컬렉션 리소스에 달려 있음
• 컬렉션 리소스는 포함하려는 항목을 선택하고 포함된 각 리소스의 URI도 결정
• 컬렉션 리소스 원형을 나타내기 위해 '복수형' 이름을 사용
  • 예: http://api.example.com/user-management/users

저장소(store)

• 클라이언트 관리 리소스 저장소
• API 클라이언트가 리소스를 넣고, 다시 꺼내고, 삭제할 시기를 결정할 수 있음
• 저장소는 새 URI를 생성하지 않고 각 저장된 리소스에 URI가 있음
• URI는 리소스가 처음에 저장소에 넣을 때 클라이언트가 선택함
• 저장소 리소스 원형을 나타내려면 '복수형' 이름을 사용
  • 예: http://api.example.com/song-management/users/{id}/playlists

컨트롤러(controller)

• 절차적 개념을 모델링
• 컨트롤러 리소스는 매개변수와 반환 값, 입력 및 출력이 있는 실행 가능한 함수와 같음
• 컨트롤러 원형을 나타내기 위해 '동사'를 사용
  • 예: http://api.example.com/song-management/users/{id}/playlist/play

일관성이 핵심

• 슬래시(/)를 사용하여 계층적 관계를 나타냄
• URI 마지막 문자로 슬래시(/)를 사용하지 않기
• 하이픈(-)을 사용하여 URI 가독성 향상
• 밑줄(_)을 사용하지 않기
• URI에 소문자 사용

파일 확장자를 사용하지 말기

• 파일 확장자는 보기에 좋지 않으며 이점이 없고, 확장자를 제거하면 URI의 길이가 줄어듦
• 파일 확장자를 사용하여 API의 미디어 유형을 강조하여 표시하려면 헤더를 통해 전달되는 미디어 유형에 의존하여 본문 내용을 처리하는 방법을 결정해야 함

URI에 CRUD 함수 이름을 사용하지 않기

• CRUD 기능을 나타내기 위해 URI를 사용해서는 안 됨
• URI는 리소스를 고유하게 식별하는 데만 사용해야 하며 리소스에 대한 처리에는 사용하지 않아야 함
• 어떤 CRUD 기능이 수행되는지 나타내기 위해 HTTP 요청 메서드를 사용해야 함

쿼리 구성 요소를 사용하여 URI 컬렉션 필터링

• 종종 특정 리소스 속성을 기반으로 리소스 컬렉션을 정렬, 필터링 또는 제한해야 하는 요구 사항에 직면하게 됨
• 새 API를 생성하지 말고 리소스 컬렉션 API에서 정렬, 필터링 및 페이지 매김 기능을 활성화하고 입력 매개변수를 쿼리 매개변수로 전달
  • 예: http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ

참고

• 원본: https://restfulapi.net/resource-naming
• https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_2_1_1