REST Resource Naming Guide

https://restfulapi.net/resource-naming/

REST API - URL Naming Conventions

1. 단수/복수 리소스

• 리소스는 싱글턴 이거나 컬렉션 일 수 있다.
• 컬렉션 리소스는 "customers" 로 식별
• 싱글턴 리소스는  "customers/{customerId}" 로 식별

2. 컬렉션 리소스와 서브 컬렉션 리소스

• 리소스가 서브 컬렉션 리소스를 가질 수 있다.
• 특정 고객의 계정 목록을 식별하고자 하는 경우
• "/customers/{customerId}/accounts"
• 비슷하게 특정 고객의 특정 계정을 식별하고자 하는 경우
• "/customers/{customerId}/accounts/{accountId}"

3. 베스트 프랙티스

• 리소스를 표현할떄는 명사를 써라
• 명사가 2개 이상이면 하이픈( - )로 이어서 적는다.
• 리소스 타입을 네가지 범주로 나누면 [문서, 컬렉션, 저장소, 컨트롤러] 로 나눠진다.
• 여러 범주를 한 리소스에 혼합하는 설계하는것을 지양해야 합니다.
• 마지막에 빈 슬래시를 안붙이는 것이 더 좋다.
• 언더스코어( _ )를 쓰지 마라.(특정 폰트에서 안보일 수도 있기 떄문)
• 대문자를 쓰지 마라.
• 파일 확장자를 쓰지 마라. --> 유지할 필요가 없다. 어던 미디어 타입을 가져오는지 명시하고 싶으면 media type을 사용하면 된다. Content-Type 헤더에 있음
• CRUD 함수 동사를 직접 적지 마라. CRUD는 HTTP Method로 처리한다.
• HTTP Method로 처리할 수 없는 작업의 경우에만 불가피하게 POST에 동사를 사용하여 처리한다.

 

4. 용어 설

•  문서
  • 단일 리소스를 가리킴
• 컬렉션
  • 서버에서 관리되는 리소스 경로
  • 복수 리소스를 가리킴
• 스토어
  • 클라이언트에서 관리되는 리소스 저장소
• 컨트롤러
  • 컨트롤러 리소스 모델은 절차적인 컨셉이다.
  • 실행가능한 함수와 같다.
  • 파라미터와 반환값을 가지고있음
  • 동사로 나타내진다.