REST API URI 설계 규칙

API 네이밍을 하다가 고민이 생겼다.

[PUT] /urls/{id}/move과 [PUT] /urls/move/{id} 중 어떤 게 더 나은지 말이다.

이를 위해 구글링을 하다가, REST API URI를 디자인하는 규칙 혹은 컨벤션이 존재한다는 것을 알게 되었다.

 

 

REST API와 URI

REST API는 Representational State Transfer (표현 상태 전송)의 약자이며, 웹 기반의 시스템 간 통신을 위한 아키텍처 스타일이다. 이 방식은 자원(Resource)의 상태를 HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하여 전송하는 방식으로 구현된다. 각 자원은 특정한 URI(Uniform Resource Identifier, 통일된 자원 식별자)에 의해 식별된다.

URI는 인터넷 상의 자원을 나타내는 유일한 주소로, 웹 페이지, 이미지, 파일 등을 위치 지정하기 위해 사용된다. REST API에서 URI는 특정 자원 또는 자원의 컬렉션에 대한 접근을 제공하며, HTTP 메서드와 함께 사용되어 해당 자원에 대한 다양한 작업(조회, 생성, 수정, 삭제 등)을 수행한다.

 

 

REST API URI 설계를 위한 종합 가이드

REST API URI 설계에 있어 중요한 규칙들을 다음과 같이 종합할 수 있었다.

 

1. 마지막 슬래시(/) 제외: URI 끝에 슬래시를 포함하지 않는다.
   예) http://api.example.com/devices와 http://api.example.com/devices/는 동일해야 한다.
2. 계층적 관계 표현: 슬래시(/)는 리소스 간의 계층적 관계를 나타낸다.
   예) http://api.canvas.com/shapes/polygons/quadrilaterals/squares
3. 하이픈(-) 사용: URI의 가독성을 높이기 위해 긴 경로 세그먼트에서 하이픈을 사용한다.
   예) http://api.example.com/device-management/managed-devices
4. 언더스코어(_) 사용 금지: URI에서는 언더스코어(_) 대신 하이픈(-)을 사용한다.
5. 소문자 사용 권장: URI 경로에서는 소문자를 사용하는 것이 좋다.
6. 파일 확장자 제외: URI에서는 파일 확장자를 사용하지 않는다.
7. 명사 사용: URI는 자원을 나타내는 데 명사를 사용하며, 동사는 사용하지 않는다.
8. CRUD 함수 이름 사용 금지: URI는 자원을 식별하는 데 사용되며, CRUD 작업은 HTTP 요청 메소드를 통해 수행된다.
9. 쿼리 컴포넌트 사용: 필터링, 정렬, 페이징 등은 쿼리 매개변수를 통해 수행된다.
10. 자원의 단일 및 집합 구분: 'customers'는 집합 자원, 'customer'는 단일 자원을 나타낸다.
    예) /customers는 모든 고객을 나타내고, /customers/{customerId}는 특정 고객을 나타낸다.

 

 

[PUT] /urls/{id}/move 과 [PUT] /urls/move/{id}의 의미가 다르다

공부한 내용에 따라, 내가 처음에 고민했던 두 URI의 의미가 다르게 해석될 수 있다는 것을 알게 되었다.

 

1. [PUT] /filecomponenturls/{id}/move
   • 이 구조는 "move" 동작이 {id}로 식별되는 특정 "urls"에 적용됨을 나타낸다.
   • "urls"이 주 리소스이며, "move"는 이 리소스에 대한 특정 동작임을 의미한다.
   • URL이 리소스를 대표하고 HTTP 메소드(여기서는 PUT)가 동작을 대표하는 RESTful 원칙과 일치한다.
2. [PUT] /filecomponenturls/move/{id}
   • 이 구조는 "move"를 "filecomponenturls" 아래의 하위 리소스나 동작 범주로 위치시킨다.
   • "move"라는 넓은 범주 아래에서 특정 {id}를 이동시킴을 나타낸다.
   • "urls" 아래에 다양한 동작(예: move, copy, delete)을 분류하고자 할 때 적합하다.

 

첫 번째 옵션인 [PUT] /filecomponenturls/{id}/move 가 더 RESTful 하다!

"move" 동작이 {id}로 식별되는 특정 url에 수행됨을 명확히 할 수 있기 때문이다.

 

URI를 설계할 때, 계층 구조를 명확히 표현하고 API 사용자가 이해하기 쉽도록 설계해야겠다고 느낄 수 있었다.

 

 

 

ref

https://dzone.com/articles/7-rules-for-rest-api-uri-design-1

7 Rules for REST API URI Design - DZone

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

REST API URI Naming Conventions and Best Practices