REST API URI 규칙

REST API URI 설계 규칙

모든 필수적인 자원 정보들을 소통하는데 있어서 가독성 있고 규칙에 위반되지 않은 URI 작성을 위한 규칙

 

URIs

REST API는 자원의 주소를 나타내기 위해 Uniform Resource Identifiers(URIs)를 사용함

Client들은 웹의 연결 패러다임을 따라야 하며 URI를 불확실한 식별자로 대우해야 함, REST API 디자이너들은 잠재적 Client 개발자들에게 REST API의 자원 정보를 전달할 수 있는 URI를 만들어야 함

 

#1. URI에 후행 슬래시(주소 마지막에 붙이는 /)는 포함되지 않아야 됨

혼란을 줄 수 있고 의미가 없는 후행 슬래시를 URI 경로의 마지막에 포함시키지 않는 것은 규칙 중 가장 중요한 것 중 하나임.

REST API는 후행 슬래시를 가지지 않아야 하고 Client들에게 제공하는 링크에 후행 슬래시는 포함되지 않아야 함

 

많은 웹 구성 요소와 프레임워크는 다음 두 개의 URI를 같게 인식함.

http://api.canvas.com/shapes/ 

http://api.canvas.com/shapes 

 

그러나 URI 내의 모든 문자는 리소스의 고유 ID에 포함되고, 두 개의 다른 URI는 두개의 다른 리소스에 매핑 됨.

URI가 다르면 리소스도 다르고 그 반대도 마찬가지임, 그러므로 REST API는 명확한 URI를 생성해야 한다.

BAD
http://api.canvas.com/shapes/

Good
http://api.canvas.com/shapes

 

 

#2. 슬래시(/)는 계층 관계를 나타내는 데 사용

슬래시(/) 문자는 URI의 경로 부분에서 resource들 간의 계층 관계를 나태내는데 사용됨.

• 행위는 포함하지 않는다, 행위는 URI 대신 Method를 사용하여 전달한다.

Bad
http://api.college.com/get-students

Good
http://api.college.com/students/

 

 

#3. 언더바(_) 대신 하이픈(-)을 사용

가독성을 위해 긴 Path(경로)를 표현하는 단어는 하이픈으로 구분하는 것이 좋음, 프로그램의 글자 폰트에 따라서 언더바 문자는 문자가 부분적으로 가려지거나 숨겨질 수 있음

BAD
http://api.example.com/blogs/guy-levin/posts/this_is_my_first_post

GOOD
http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

 

 

#4. URI 경로는 소문자를 사용

대문자는 때로 문제를 일으키는 경우가 있기 때문에 URI를 작성할 때는 소문자를 선호한다.

RFC 3986은 URI를 Schema 혹은 호스트 구성요소를 제외하고 URI를 대소문자를 구분하여 정의함

BAD
http://api.example.com/firstProject

GOOD
http://api.example.com/first-project

 

 

#5. 파일 확장자는 URI에 포함시키지 않는다

파일 확장자는 URI에 포함하지 않는다, 대신 Content-Type이라는 헤더를 통해 전달되는 대로 미디어 타입을 사용하여 body의 콘텐츠를 처리하는 방법을 결정함

REST API 클라이언트는 HTTP에서 제공하는 형식 선택 메커니즘 Accept 요청 헤더를 활용하도록 권장해야 함

Bad
http://api.college.com/students/3248234/courses/2005/fall.json

Good
http://api.college.com/students/3248234/courses/2005/fall

 

 

#6. 전달하고자 하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.

BAD
http://api.college.com/course/writing

GOOD
http://api.college.com/course/write

 

문서(Document)

• 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
• 단수 사용 (/device-management, /user-management)

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

 

컬렉션(Collection)

• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스의 URI를 생성하고 관리
• 복수를 사용하라
• POST 기반 등록
• 예) 회원 관리 API
• 복수 사용 (/users)

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

 

스토어(Store)

• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• PUT 기반 등록
• 예) 정적 컨텐츠 관리, 원격 파일 관리
• 복수 사용 (/files)

http://api.example.com/files
http://api.example.com/files/new_file.txt

 

컨트롤 URI 혹은 컨트롤러(Controller)

• 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
• 동사를 직접 사용
• 예) GET, POST만 사용할 수 있는 HTTP FORM의 경우 컨트롤 URI(동사로 된 리소스 경로)를 사용 ex) /members/delete, /members/new 등
• 동사 사용 (/checkout, /play 등)

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

 

#7. URI에 작성되는 영어를 복수형으로 작성

관계가 다른 리소스 내에서만 존재할 경우 RESTful 원칙은 다음과 같은 지침을 제공

http://api.college.com/students/3248234/courses
ID가 3248234인 학생이 학습한 모든 과정 목록 검색 
http://api.college.com/students/3248234/courses/physics
ID가 3248234인 학생을 위한 과정 물리학을 검색

 

 

#8. CRUD 함수명을 사용하지 마라 

URI는 어떤 동작이 수행되는지 가르키는 게 아니라, 리소스 가르키는 것이다.

리소스에 대한 작업은 HTTP Method를 사용해라

HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device
HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id

 

 

#9. 필터를 위해 쿼리 파라미터를 사용해라

Resource(or Reperesentation)에 대한 정렬, 필터링, 페이징 신규 API를 생성하지 않고 쿼리 파라미터를 활용

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date