[HTTP] 리소스 URI 네이밍 규칙과 베스트 프랙티스

1.  리소스란 ?

- REST에서 리소스는 URI로 식별되는 모든 데이터(문서, 이미지, 서비스, 객체 등)를 의미.
- 리소스는 단일 객체(싱글턴)일 수도 있고, 여러 객체의 모음(컬렉션)일 수도 있다. ->  /customers(컬렉션), /customers/{id}(싱글턴)
- 컬렉션 리소스 안에 서브 컬렉션 리소스가 있을 수 있다.->  예: /customers/{customerId}/accounts (특정 고객의 계정 목록)

---

2. 리소스 네이밍 베스트 프랙티스

 

2.1. 명사 사용

- URI에는 동사가 아니라 명사를 사용해 리소스를 표현해야 한다.
- 리소스 유형은 다음 세 가지로 구분할 수 있다.
  - Document(문서): 단일 객체, 단수형 사용 (/users/{id})
  - Collection(컬렉션): 객체의 집합, 복수형 사용 (/users)
  - Store(저장소): 클라이언트가 관리하는 리소스 저장소, 복수형 사용 (/users/{id}/playlists)

2.2. 일관성 유지

- 슬래시(/)로 계층적 관계를 표현하기 -> /device-management/managed-devices/{id}/scripts
- 트레일링 슬래시(/)는 사용하지 않는다. (/users/ → X, /users → O)
- 하이픈(-)을 사용해 가독성을 높인다. (/managed-devices) , (_) 언더바는 사용X
- 소문자만 사용한다.
- 파일 확장자는 붙이지 않는다. (미디어 타입은 Content-Type 헤더로 구분)

2.3. CRUD 함수명(동사) 사용 금지

- URI에 get, create, update, delete 등 동사를 넣지 않는다.
- HTTP 메서드(GET, POST, PUT, DELETE 등)로 동작을 구분한다.
- 단 HTTP 메서드만으로 완전 구분이 어려운 경우에는 Control URI 사용한다 -> 하지만 무분별한 사용금지
예를 들면 HTML FORM 사용시 GET, POST 메서드만 지원하기 때문에, 삭제 로직 작성시 POST 메서드로 다음과 같이 컨트롤 URI를 작성 -> /members/{member-id}/delete

2.4. 컬렉션 필터링은 쿼리 파라미터 사용

- 정렬, 필터, 페이징 등은 쿼리 파라미터로 처리한다. -> 예: /managed-devices region=USA&brand=XYZ&sort=installation-date

---

3. 결론

- 리소스 네이밍은 명사로, 일관성 있게, 가독성 있게, 동사 및 파일 확장자 사용 금지
- URI는 리소스를 식별하는 역할만 하며, 동작은 HTTP 메서드(GET,POST,PUT,PATCH 등)로 구분해야한다.