[번역글] REST API URI를 결정하는 7가지 규칙

REST API URI를 결정하는 7가지 규칙

7가지 규칙은 파악하기 쉽고 필요한 모든 자원과 정보를 전달하는 충돌위험이 적은 URI를 쓸 수 있도록 해줄 것입니다.

REST API URI 규칙에 대해 넘어가기 전에 우리가 다룰 URI라는 용어에 대해서 짚고 넘어가도록 하겠습니다.

 

URI

REST API는 주소자원으로 URI(Uniform Resource Identifiers)를 사용합니다. 오늘날의 웹에서 URI 디자인은 API의 리소스 모델을 명확하게 전달하는 걸작부터 사람들이 이해하기 어려운 것까지 다양합니다.

팀버너스 리는 “웹 아키텍처의 원칙”이라는 목록에 URI의 불투명성(“”식별자를 사용할 수 있는 유일한 것은 객체를 참조하는 것”)에 대해 기재하였습니다. 역 참조하지 않을 때는 다른 정보를 얻기 위해 URI 문자열의 내용을 보지 않아야합니다.

클라이언트는 웹의 링크 패러다임을 따라야하며 URI를 불완전한 식별자로 취급해야합니다.

REST API 설계자는 REST API가 반환하는 자원을 잠재적 클라이언트 개발자에게 전달할 URI를 만들어내야합니다. 이번 포스팅에서는 REST API의 URI를 결정하는 몇가지 디자인 규칙을 소개하고자 합니다.

규칙을 살펴보기 전, 이 세션에 제시된 규칙에 따라 URI 형식에 대한 단어는 URI 형식과 관련이 있습니다. RFC3986은 아래와같이 일반 URI 구문을 정의하였습니다.

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

 

 

- 규칙 1 : 후행 슬래쉬(/)는 URI에 포함되지 않아야 합니다. 

이것은 URI의 경로를 결정하는 마지막 문자로써 반드시 따라야하는 것입니다. 후행 슬래쉬는 의미가 전혀 없을 뿐아니라 혼란을 야기합니다. REST API에서는 클라이언트 개발자에게 넘어가는 API URI에 후행 슬래쉬가 있을 수 있다고 생각해서는 안됩니다. 

많은 웹 컴포넌트나 프레임워크들은 다음의 두 URI를 동일하게 다룹니다.

http://moretranslate.co.kr/moretranslate

http://moretranslate.co.kr/moretranslate/

그러나 URI에 있는 모든 문자들은 리소스의 고유한 ID로 계산됩니다. 

두개의 다른 URI는 다른 2개의 리소스로 매핑됩니다. URI가 다르다면 리소스도 달라집니다. 그래서 REST API는 명확한 URI를 생성해야합니다. 또한 클라이언트가 부정확하게 접근하려는 시도들을 모두 고려하여야 합니다. 우리의 개발 파트너인 클라이언트만이 API 호출 대상이 아니기 때문입니다. 

 

 

- 규칙 2 : 계층관계를 나타낼 때 슬래시 구분자를 사용해야합니다.

슬래시문자는 URI의 경로 부분에서 자원 간의 계층적 관계를 나타내기 위해서 사용합니다.

예를 들어, http://board.com/board/52 -> 게시판의 52번글.

 

 

- 규칙 3 : URI의 가독성을 높이기 위해서 하이픈(-) 문자를 사용합니다.

당신이 정의한 URI가 사람들에게 더 쉽게 읽힐 수 있게 하기 위해서 긴 Path를 표현하는 단어는 하이픈으로 구분해두는 것이 좋습니다. 

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

 

 

- 규칙 4 : 언더바( _ ) 문자는 URI에 사용하지 않습니다.

텍스트 뷰어 프로그램은(예를 들어, 브라우저, 에디터 등) 클릭할 수 있다는 것을 표현하기 위해 URI에 밑줄을 그어 놓습니다. 프로그램의 글자 폰트에 따라서 언더바 문자( _ )는 이러한 밑줄처리에 의해 문자가 부분적으로 가려지거나 완전히 숨겨질 수 있습니다.

이러한 혼란을 피하기위해 언더바 문자보다는 하이픈 문자를 사용하시는 것이 좋습니다.

 

 

- 규칙 5 : URI를 작성하는 데에는 소문자가 적합하다.

대문자는 때로 문제를 일으키는 경우가 있기 때문에 URI를 작성할 때는 소문자를 선호합니다. RFC3986은 체계 및 호스트 구성요소를 제외하고 URI를 대소문자를 구분하여 정의합니다.

 

 

- 규칙 6 : 파일확장자는 URI에 포함하지 않습니다.

웹상에서 점( . )은 파일명과 확장자를 구분짓는 데에 사용되는 문자입니다. REST API는 메시지 엔티티 바디의 본문 형식을 표시하기 위해 이러한 파일 확장자를 URI에 포함하지 말아야합니다. 대신에 Content-Type이라는 헤더를 통해 전달되는대로 미디어 타입을 사용하여 body의 콘텐츠를 처리하는 방법을 결정합니다.

http://test.com/student/232323/courses/2019/fall.json

http://test.com/student/232323/courses/2019/fall

파일 확장자는 형식 표현하기 위해 나타내면 안됩니다. REST API 클라이언트는 HTTP에서 제공한 형식 선택 매커니즘인 Accept 요청헤더를 사용해야 합니다.

손쉬운 링크와 디버깅을 위해서, REST API는 쿼리스트링 매개변수를 통해 미디어 타입 선택을 지원합니다.

 

 

- 규칙 7 : 보통 URI는 영어로 작성되는데 작성되는 영어를 단수형으로 작성해야하는가 복수형으로 작성해야 하는가?

단순유지(keep-it-simple) 규칙이 여기에 적용됩니다. 하나의 인스턴스를 복수형으로 표시하는게 영어문법적으로 맞지 않겠다고 생각할 수도 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있습니다. 

이상한 복수형(person/people과 같은)을 다루지 않아도 API 소비자가 편하게 이용하고 API 제공업체가 구현하기가 쉬워집니다. (대부분의 최신 프레임워크가 /students(복수형) 및 /students/232324(복수형 중 특정하기) 형태로 처리됨) 

그런데 관계는 어떻게 다룰까? 관계가 다른 리소스내에서만 존재할 경우 RESTFUL 원칙은 유용한 지침을 제공합니다. 예를 들어, 학생은 많은 코스를 가지고 있고, 코스는 다음과 같이 /students 에 매핑됩니다.

 

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

 

결론

REST API 서비스를 디자인할 때, URL을 디자인할 resource에(students와 같은) 주의를 많이 기울여야 합니다. 

서비스의 모든 리소스들은 최소 하나의 URI로 구분할 것입니다. 특정 URI가 리소스를 적절히 설명할 수 있을 때 가장 좋은 디자인입니다. URI는 이해력을 높이기 위해서 예측 가능해야하고, 계층 구조적이어야 합니다. 즉, 일관성이 있다는 관점에서 예측가능하고, 데이터가 구조를 갖추고 있다는 점에서 계층적이다는 것입니다.

RESTFul API는 소비자가 있습니다. URI의 이름이나 구조는 이러한 소비자에게 의미를 전달할 수 있어야 합니다. 위의 규칙들을 따라봄으로써 더욱 명확한 REST API를 구축해볼 수 있을 것이고 API를 호출하는 클라이언트 개발자는 행복하게 여러분이 작성한 API를 사용할 수 있을 것입니다. 반드시 지켜야하는 제약같은 것이 아닙니다. 여러분이 위의 규칙들을 준수해봄으로써 API는 강력해질 수 있을 것입니다.

 

 

 

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