REST API URI를 설계하는 7가지 규칙

최근 백엔드를 구현하던 중 uri를 규칙없이 작성하는 것 같아 여러글을 찾아보다가 

잘 쓰여진 글이 있는 것 같아 가져가고 싶었습니다.

 

해당 포스트는 아래에 첨부된 사이트를 번역한 글입니다. (오역이 있을 수 있습니다.)

 

1. URI 마지막에 슬래시(/)를 붙이지 마세요 
2. 관계를 나타내기 위해 슬래시(/)를 사용하세요
3. 하이픈(-)를 사용하세요 
4. 언더바(_)를 사용하지 마세요
5. 소문자를 선호하세요
6. URI에 파일 확장자를 사용하지 마세요
7. 복수형을 사용하세요

 

REST API URI를 설계하는 7가지 규칙

아래에 열거된 7개의 단순한 규칙은 모든 필수적인 자원 정보들을 소통하는데 있어서 가독성 있고 규칙에 위반되지 않는 URI들을 작성하게 도와줄 겁니다.

 

REST API URI 설계 규칙을 알아보기 전에 우리가 이야기할 용어들에 대해 빠르게 살펴봅시다

 

URIs

REST API는 자원의 주소를 나타내기 위해 Uniform Resource Identifiers (URIs)를 사용합니다. 오늘날의 웹에서 URI 설계는 사람들이 이해하기 어려운 것 에서 부터 API 자원들과 깔끔하게 소통하는 대작까지 다양하다.

Tim Berners-Lee는 그의 "Axioms of Web Architecture"리스트 에서 URI의 불분명성에 대해 언급하였다. "식별자를 사용할 수 있는 유일한 방법은 객체를 참조하는 것입니다. 비참조를 하지 않을때는 다른 정보를 얻기 위해 URI 문자의 내용을 보지 않아야 합니다"

 

Client 들은 웹의 연결 패러다임을 따라야 하며 URI를 불확실한 식별자로 대우해야 합니다.

 

REST API 디자이너들은 잠재적 client 개발자 들에게 REST API의 자원 정보를 전달할 수 있는 URI를 만들어야 합니다. 이 포스트에서 

REST API URI 설계 규칙들을 소개할 것입니다.

 

규칙들을 따르기 전에 URI 형식과 관련된 규칙으로서 URI 형식에 대한 단어 RFC 3986은 일반적인 URI 문법을 아래에 보이는 것과 같이 정의하였습니다.

 

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

 

첫번째 규칙

URI에 후행 슬래시(/ => 마지막에 붙이는 슬래시) 는 포함되지 않아야 합니다.

 

혼란을 줄수 있고 의미가 없는 후행 슬래시를 URI 경로의 마지막에  포함시키지 않는 것은 따라야 할 규칙들 중 가장 중요한 것중 하나 입니다. REST API는 후행 슬래시를 가지지 않아야 하고 client들에게 제공하는 링크에 후행 슬래시는 포함되지 않아야 합니다.

 

많은 웹 component들과 framework들은 아래 두개의 URI를 같게 인식합니다 :
http://api.canvas.com/shapes/
http://api.canvas.com/shapes

 

그러나 URI의 모든 글자들은 resource들의 고유한 구별자로 계산됩니다.

 

두개의 다른 URI는 두개의 다른 resource들을 가리킵니다. 만약 URI가 다르다면 resource들도 다른것입니다, 그 반대또한 마찬가지 구요. 그러므로 REST API는 깨끗한 URI를 생성하고 소통해야 하며 resource를 모호하게 식별하려는 client의 시도를 허용하지 않아야 합니다.

 

더 너그러운 API 들은 후행 슬래시 없이 client들을 URI로 리다이렉트 시킬 것입니다.(301을 반환할수도 있다 -"영원히 이동" 자원들을 재위치 시키기 위해 사용되어지곤 한다.)

Rule #2

슬래시(/)는 계층관계를 나타내는데 사용해야 합니다.

 

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

For example: http://api.canvas.com/shapes/polygons/quadrilaterals/squares

Rule #3

URI의 가독성을 위해 하이픈(-)을 사용해야 합니다.

 

URI를 사람에게 쉽게 인식되고 해석되게 하고, 긴 경로 요소 이름의 가독성을 증가 시키기 위해 하이픈(-)을 사용하세요. 영어로 공백이나 하이픈을 사용할 경우 URI에 하이픈을 사용해야 합니다.

 

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

Rule #4

URI에서 언더바(_)는 사용하지 않아야 합니다.

 

텍스트 viewer 어플리케이션들(브라우저, 에디터, 등등)은 종종 URI에 클릭할수 있다는 시각적 힌트를 주기위해 밑줄을 사용합니다.

어플리케이션의 폰트에 따라 언더바(_) 문자는 밑줄로 인해 부분적으로 보이지 않거나 완전히 가려질 수 있습니다.

 

이러한 혼란을 피하기 위해 언더바(_) 대신 하이픈(-)을 사용하세요

Rule #5

URI 경로에서는 소문자를 선호합니다.

 

대문자가 문제를 일으킬 수 있으므로 URI 경로에서는 소문자를 선호하는 것이 편리합니다.

RFC 3986은 URI를 scheme 혹은 host component를 제외하고 대소문자를 구분하는 것으로 정의하였습니다.

 

For example:
1) http://api.example.com/my-folder/my-doc

2) HTTP://API.EXAMPLE.COM/my-folder/my-doc 

위의 uri는 괜찮습니다. RFC 3986에서는 1번 URI와 같은 것으로 인식합니다.

3) http://api.example.com/My-Folder/my-doc

이 URI는 1번, 2번과 같지 않습니다. 불필요한 혼란을 가져올 수 있습니다.

Rule #6

URI에 파일 확장자는 포함되지 않아야 합니다.

 

웹상에서 마침표(.) 문자는 URI에서 파일의 이름과 확장자를 구분하는데 흔히 사용됩니다. REST API는 메시지들의 객체 body를 나타내는 위해 URI에 임의의 파일 확장자를 포함하지 않아야 합니다. 대신 body의 내용이 어떻게 흐르는지 결정하는 Content-Type header를 통해 전달되는 media-type에 의존하여야 합니다.

 

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

 

파일 확장자는 format 선호를 나타내기위해 사용되면 안됩니다.

 

REST API client들은 HTTP가 제공하는 형식 선택 메커니즘인 Accpet request 헤더를 사용하도록 해야 합니다.

 

간단한 link들과 쉬운 디버깅을 가능하게 하기 위해 REST API는 query parameter를 통해 미디어 타입 선택을 지원할수 있습니다.

 

Rule #7

마지막 부분은 단수 또는 복수형이여야 할까요? (복수형을 사용하라)

 

간단하게 유지하라는 규칙은 이곳에도 적용됩니다. 비록 각자 내재화된 문법규칙이 single instance나 resource를 나타내기 위해 복수형을 사용하는 것이 틀렸다고 할지라도 프로그래밍적 정답은 URI 형식에서 항상 복수형을 사용하라는 것입니다.

 

불규칙 복수형(person/people, goose/geese)들은 다루지 않는것이 API 사용자들의 생활을 더 좋고 API 제공자들이 더 쉽게 수행할수 있도록 만들어 줍니다.(대부분의 현대 프레임워크들은 /students와 /students/3248234를 같은 컨트롤러에서 다룹니다.)

 

그런데 관계들은 어떻게 다루어야 할까요? 관계가 다른 자원 내에서만 존재할 수 있는 경우 RESTful 원칙은 유용한 원칙을 제공합니다.

예시를 한번 살펴볼게요. 한 학생이 복수개의 과목을 가지고 있습니다. 이 과목들은 /studensts의 끝 부분에 위치하게 됩니다.

 

http://api.college.com/students/3248234/courses - id 3248234를 가진 학생이 배운 모든 과목들을 반환합니다.
http://api.college.com/students/3248234/courses/physics - id 3248234를 가진 학생이 배운 물리학 과목들을 반환합니다.

Conclusion

REST API 서비스를 설계할때 URI에 나타내어지는 resource들에 집중을 해야합니다.

 

서비스 내의 각각의 resource들은 하나 이상의 URI 식별자를 가지게 될것입니다. URI가 이해하기 쉽고 적절히 resource를 나타내는 것이 가장 좋습니다. URI는 예측가능해야 하며 이해력을 높이기 위해 계층구조를 사용해야 하고 사용성은 데이터가 구조 관계를 가지고 있다는 점에서 일관되고 계층적이라는 점에서 예측 가능해야 합니다.

 

RESTful API들은 사용자를 위해 작성되어져야 합니다. URI의 이름과 구조는 사용자들에게 의미를 전달해야 합니다. 위의 규칙들을 따름으로써 client를 좀 더 행복하게 하는 훨씬 깔끔한 REST API들을 만들수 있을 것입니다. 이것은 규칙이나 제약조건이 나니지만 API를 향상 시킬 것입니다.

 

이러한 가이드라인을 살펴보는 것을 추가로 제안할게요

 

데이터를 위한것이 아닌 client들을 위해 설계하세요

 

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

7 Rules for REST API URI Design - DZone Integration