REST API URI 디자인에 대한 7가지 규칙

thumb

REST API URI 디자인에 대한 7가지 규칙

REST API URI 디자인에 대한 규칙을 살펴보기 전에 우리가 이야기할 몇 가지 용어에 대해 간략하게 살펴보겠습니다. URI

REST API는 URI를 사용하여 리소스의 주소를 지정합니다. 오늘날의 웹에서 URI 디자인은 다음과 같이 API의 리소스 모델을 명확하게 전달하는 걸작 http://api.example.com/louvre/leonardo-da-vinci/mona-lisa 부터 사람들이 이해하기 훨씬 어려운 것 까지 다양합니다. http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66

Tim Berners-Lee는 "웹 아키텍처의 공리"목록에 URI의 불투명도에 대한 메모를 포함 시켰습니다.

식별자를 사용할 수있는 유일한 방법은 객체를 참조하는 것입니다. 역참조하지 않는 경우 다른 정보를 얻기 위해 URI 문자열의 내용을 확인해서는 안 됩니다.
- Tim Berners-Lee

클라이언트는 웹의 연결 패러다임을 따라야 하며 URI를 불투명 식별자로 처리해야 합니다.

REST API 디자이너는 REST API의 리소스 모델을 잠재적 클라이언트 개발자에게 전달하는 URI를 만들어야 합니다. 이 게시물에서는 REST API URI에 대한 일련의 디자인 규칙을 소개하려고 합니다.

규칙을 살펴보기 전에 이 섹션에 제공된 규칙과 같은 URI 형식에 대한 단어는 URI 형식과 관련이 있습니다.
RFC 3986은 아래와 같이 일반 URI 구문을 정의합니다.

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

규칙 #1: 후행 슬래시(/)는 URI에 포함되어서는 안 됩니다.

이것은 따라야 할 가장 중요한 규칙 중 하나이며 URI 경로의 마지막 문자로 슬래시(/)는 의미 체계 값을 추가하지 않으며 혼동을 일으킬 수 있습니다. REST API는 후행 슬래시를 예상해서는 안 되며 클라이언트에 제공하는 링크에 포함하지 않아야 합니다.

많은 웹 구성 요소와 프레임워크는 다음 두 URI를 동일하게 처리합니다.
http://api.canvas.com/shapes/
http://api.canvas.com/shapes

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

두 개의 서로 다른 URI가 두 개의 서로 다른 리소스에 매핑됩니다. URI가 다르면 리소스도 다르고 그 반대의 경우도 마찬가지입니다. 따라서 REST API는 깨끗한 URI를 생성하고 전달해야 하며 리소스를 부정확하게 식별하려는 클라이언트의 시도를 허용하지 않아야 합니다.

더 관대한 API는 클라이언트를 후행 슬래시 없이 URI로 리디렉션할 수 있습니다(리소스를 재배치하는 데 사용되는 301 – "영구적으로 이동됨"을 반환할 수도 있음).

규칙 #2: 슬래시 구분 기호(/)는 계층적 관계를 나타내는 데 사용해야 합니다.

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

예를 들면 다음과
같습니다 http://api.canvas.com/shapes/polygons/quadrilaterals/squares

규칙 #3: 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를 대/소문자를 구분하는 것으로 정의합니다.

예를 들면 다음과
같습니다 http://api.example.com/my-folder/my-doc

HTTP://API.EXAMPLE.COM/my-folder/my-doc
이 URI는 괜찮습니다. URI 형식 사양(RFC 3986)은 이 URI를 URI #1과 동일한 것으로 간주합니다.

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에서 제공하는 형식 선택 메커니즘인 요청 수락 헤더를 활용하도록 권장해야 합니다.

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

규칙 #7: 엔드포인트 이름은 단수여야 합니까 아니면 복수여야 합니까?

단순하게 유지 규칙이 여기에 적용됩니다. 내부 문법자는 복수형을 사용하여 리소스의 단일 인스턴스를 설명하는 것이 잘못되었다고 말하지만 실용적인 대답은 URI 형식을 일관되게 유지하고 항상 복수형을 사용하는 것입니다.

이상한 복수화 (사람 / 사람, 거위 / 거위)를 처리 할 필요가 없으므로 API 소비자의 삶이 향상되고 API 공급자가 구현하기가 더 쉽습니다 (대부분의 최신 프레임 워크는 기본적으로 공통 컨트롤러 에서 / students 및 / students/3248234를 처리합니다).

그러나 관계를 어떻게 처리합니까? 관계가 다른 리소스 내에서만 존재할 수있는 경우 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를 만들 수 있습니다. 이는 REST 규칙 또는 제약 조건이 아니지만 API를 향상시킵니다.

 

출처 : 7 Rules for REST API URI Design (restcase.com)

7 Rules for REST API URI Design