REST API URI의 7가지 규칙

 

 

 

 

 

REST API URI의 규칙에 대해 알아보기 전에 용어에 대해 간략히 짚고 넘어가도록 하겠습니다.

 

 

 

 

URI

 

REST API는 URL를 사용합니다. 오늘날의 웹에서 URI 디자인은 API의 리소스 모델을 명확하게 전달하는 걸작부터 사람들이 이해하기 힘들어하는 것까지 다양합니다.

 

팀버너스 리는 "웹 아키텍처의 원칙"이라는 목록에 URI의 불투명성에 대한 메모를 기재하였습니다.

"식별자를 사용할 수 있는 유일한 것은 객체를 참조하는 것입니다. 역참조하지 않을 때는 다른 정보를 얻으려면 URI 문자열의 내용을 참조하십시오."

 

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

 

REST API 디자이너는 REST AP의 리소스 모델을 잠재적 클라이언트 개발자에게 전달하는 URI를 만들어야 합니다.

이번 포스팅에서는 REST API URI의 몇 가지 디자인 규칙을 소개하고자 합니다.

 

규칙에 대해 알아보기 전에 이 섹션에서 제시하는 규칙에 따라 URI 형식에 대한 단어는 URI 형식과 관련이 있습니다. RFC 3986은 아래와 같이 일반 URI 구문을 정의하였습니다.

 

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

 

 

---

 

규칙 1

후행 슬래시(/)는 URI에 포함되지 않아야 한다

 

이것은 URI 경로를 결정하는 마지막 문자로써 반드시 따라야 하는 아주 중요한 규칙 중 하나입니다. 슬래시는 의미가 전혀 없을 뿐만 아니라 혼동을 일으킬 수 있습니다. REST API에서는 클라이언트 개발자에게 넘어가는 API URL에 후행 슬래시가 포함되지 않아야 합니다.

 

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

http://moretranslate.co.kr/moretranslate

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

 

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

 

2개의 다른 URI는 다른 2개의 리소스에 매핑됩니다. URI가 다르면 리소스도 달라집니다. 그래서 REST API는 깨끗하고 명확한 URI를 생성하고 전달해야 합니다. 또한 클라이언트가 부정확하게 접근하려는 시도들을 모두 용납하지 않아야 합니다.

우리의 개발 파트너인 클라이언트만이 API 호출 대상이 아니기 때문입니다.

 

 

 

 

 

규칙 2

계층 관계를 나타낼 때 슬래시 구분자(/)를 사용해야 한다

 

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

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

 

 

 

 

 

 

규칙 3

URI의 가독성을 높이기 위해서 하이픈(-) 문자를 사용한다

 

당신이 정의한 URI가 사람들에게 더 쉽게 읽힐 수 있도록 하이픈 문자를 사용하십시오. 영어로 공백이나 하이픈을 사용하는 모든 곳에서 URI에 하이픈을 사용해야 합니다.

URI를 사람들이 쉽게 스캔하고 해석할 수 있도록 하이픈(-) 문자를 사용하여 긴 경로 세그먼트에서 이름의 가독성을 향상시키십시오. 영어로 공백이나 하이픈을 사용하는 모든 곳에서 URI에 하이픈을 사용해야 합니다.

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

 

 

 

 

 

 

규칙 4

언더바(_) 문자는 URI에 사용하지 않는다

 

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

 

이러한 혼란을 방지하려면 밑줄(_) 대신 하이픈(-) 문자를 사용하시는 것이 좋습니다.

 

 

 

 

 

 

규칙 5

URI를 작성하는 데에는 소문자가 적합하다

 

대문자로 인해 때로 문제가 발생하는 경우가 있기 때문에 URI를 작성할 때는 소문자를 사용하는 것이 좋습니다. RFC 3986은 체계와 호스트 구성 요소를 제외하고 URI를 대소문자를 구분하여 정의합니다. 대문자로 인해 문제가 발생할 수 있으므로 편리한 경우 URI 경로에 소문자를 사용하는 것이 좋습니다.

 

예 :

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

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

위의 URI는 괜찮습니다. URI 형식 사양(RFC 3986)은 이 URI를 URI #1과 동일한 것으로 간주합니다.

 

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

이 URI는 URI 1 및 2와 동일하지 않으므로 불필요한 혼동을 일으킬 수 있습니다.

 

 

 

 

 

 

 

규칙 6

파일 확장자는 URI에 포함하지 않는다

 

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

 

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

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

 

형식 표현하기 위해 파일 확장자를 사용해서는 안 됩니다.

 

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

 

간단한 링크와 디버깅이 가능하게 하기 위해, REST API는 쿼리 스트링 매개변수를 통해 미디어 유형 선택을 지원할 수 있습니다.

 

 

 

 

 

 

규칙 7

보통 URI는 영어로 작성되는데 작성되는 영어는 단수여야 하는가? 복수여야 하는가?

 

여기에는 단순 유지 규칙이 적용됩니다. 단일 인스턴스를 복수형으로 표시하는 게 잘못되었다고 생각할 수도 있지만 URI의 형식을 복수형으로 사용하는 것이 실무에서 많이 사용되고 있습니다. 여기에는 단순 유지 규칙이 적용됩니다. 내부 문법학자는 복수형을 사용하여 리소스의 단일 인스턴스를 설명하는 것이 잘못되었다고 말할 것이지만 실용적인 대답은 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 서비스를 디자인할 때, URI로 정의되는 리소스의 주의를 많이 기울여야 합니다.

 

서비스의 각 리소스들은 최소 하나의 URI로 식별될 것입니다. 특정 URI가 리소스를 적절하게 설명할 때 가장 좋습니다. URI는 이해 가능성과 사용성을 향상시키기 위해 예측 가능해야 하고, 계층 구조적이어야 합니다. 즉, 일관성이 있다는 관점에서 예측 가능하고, 데이터가 구조를 갖추고 있다는 점에서 계층적이다는 것입니다.

 

RESTFul API는 소비자를 위해 작성되었습니다. URI의 이름과 구조는 해당 소비자에게 의미를 전달할 수 있어야 합니다. 위의 규칙을 따르면 훨씬 더 행복한 클라이언트로 훨씬 깨끗한 REST API를 만들 수 있습니다. 이것은 반드시 지켜야 하는 제약 조건은 아닙니다. 다만 여러분이 위의 규칙들을 준수해 봄으로써 API를 향상시킬 수 있을 것입니다.

 

 

 

 

 

 

 

 

 

 

 

 

* 본문 내용은 https://dzone.com/articles/7-rules-for-rest-api-uri-design-1 를 각색한 자료입니다.

7 Rules for REST API URI Design - DZone Integration

URIs, or Uniform Resource Identifiers, should be designed to be readable and clearly communicate the API resource model. These rules will help you succeed.

dzone.com