REST API URI 생성 규칙

프로젝트에서 CRUD 로직을 리팩토링하면서 URI에 대한 고민을 하게 되었습니다.

고민하면서 제대로 URI 규칙에 대해서 알아야겠다는 생각에 글을 쓰게 되었습니다.

 

 

URI

인터넷 자원을 나타내는 고유 식별자이다. 

URI의 I는 Identifier로 인터넷 자료의 ID를 뜻하는 것이다.

이는 자료 간 URI는 유일해야한다는 것이다.

참고 사진

 

 

규칙

#1 URI 마지막에 '/'가 포함되면 안된다.

URI 경로의 마지막에 있는 슬래시(/)는 의미를 더하지 않으며 혼란을 초래할 수 있으므로, 이를 사용하는 것은 중요한 규칙 중 하나입니다.

따라서 URI 마지막에 '/'를 붙이면 안된다.

예를 들어 http://api.test.com/test/ 와 http://api.test.com/test 있다고 했을 때 웹 컴포넌트와 프레임워크에서는 같은 것으로 처리한다.

하지만 URI의 모든 문자는 리소스의 고유 ID에 포함된다. 두 개의 서로 다른 URI는 두 개의 서로 다른 리소스에 매핑된다. URI가 다르면 리소스도 다르고 같으면 리소스도 같다.

따라서 REST API를 정확한 URI로 만들고 통신을 해야하고 어떠한 정확하지 않은 리소스에 대해서 용납하지 않아야 한다.

 

#2 '/'는  계층적인 관계를 표현하기위해 사용해야한다.

'/'는 URI의 경로 부분은 리소스 간의 계층적인 관계를 표현한다.

ex) http://api.test.com/shapes/polygons/quadrilaterals/squares

 

#3 '-'는 URI의 가독성을 높여준다.

사람들이 URI를 쉽게 읽고 이해하기 위해 긴 경로 부분에 '-'를 사용한다.

ex) http://api.test.com/blogs/guy-levin/posts/this-is-my-first-post

 

#4 '_'(underscore)는 URI에 사용하면 안된다.

브라우저나 편집기 등과 같은 텍스트 뷰어 애플리케이션은 종종 URI에 밑줄을 쳐서 클릭할 수 있다는 시각적인 표현을 사용한다.

응용 프로그램의 글꼴에 따라 '_'는 부분적으로 가려지거나 안보일 수 있다.

이러한 혼란을 피하기 위해 '_' 사용하는 대신에 '-'(hyphen)를 사용한다.

 

#5 URI 경로에는 소문자를 사용하는 것을 권장한다.

대문자를 사용했을 때 때때로 문제를 일으킬 수 있기 때문에 소문자 사용을 권장한다.

RFC 3986에 따르면, URI는 스키마와 호스트 구성 요소를 제외하고 대소문자를 구별한다.

ex)

1. http://api.test.com/my-folder/my-doc
2. HTTP://API.TEST.COM/my-folder/my-doc
3. http://api.test.com/My-Folder/my-doc

위 1, 2번 URI 예시는 괜찮다. 

URI 형색 명세서(RFC 39868)는 1, 2번 URI이 동일하다고 간주한다.

하지만 3번 URI은 1과 2번 URI와 같지 않다. 이는 불필요한 혼란을 줄 수 있다.

 

#6 URI에 파일 확장자를 포함하면 안된다.

REST API는 메시지의 본문 형식을 나타내기 위해 URI에 인위적인 파일 확장자를 포함해서는 안된다.

대신, body의 내용을 처리하는 방법을 결정하기 위해 Content-Type 헤더를 통해 전달되는 미디어 타입을 활용한다.

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

(간단한 링크와 쉬운 디버깅을 가능하게 하기 위해, REST API는 쿼리 매개변수를 통해 미디어 타입 선택을 지원할 수 있다.)

 

#7 엔드포인트는 복수형으로 작성한다.

엔드포인트는 단수? 복수?

문법적으로 리소스의 단일 인스턴스를 복수형으로 설명하는 것이 잘못되었다고 생각할 수 있다.

하지만 실용적인 측면에서 URI형식을 일관되게 유지하고 항상 복수형을 사용한다.

person/people, goose/geese와 같은 복수형 문제를 처리하지 않아도 되고, /students와 /students/123을 공통 컨트롤러에서 네이티브로 처리할 수 있어 API 제공자가 구현하기도 더 쉽다.

ex)

• http://api.college.com/students/123/courses
  
  •  학생들 중 ID가 123인 학생이 수강하는 모든 강좌 목록을 가져온다.
• http://api.college.com/students/123/courses/physics
  • 학생들 중 ID가 123인 학생이 수강하는 physics 강좌를 가져온다.

 

# 8 행위를 포함하지 않는다.

행위는 URI 대신 Method를 사용하여 전달한다.

 

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

ex)

http://api.test.com/course/writing (x)

http://api.test.com/course/write (o)

 

 

(의역한 부분도 있어서 잘못된 부분이 있거나 혹여나 누락된 부분이 있으면 댓글 달아주시면 감사하곘습니다.:))

참고

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

7 Rules for REST API URI Design - DZone

 

https://grape-blog.tistory.com/10

URI, URL 이란?

https://dev-cool.tistory.com/32

REST API URL 규칙