RFC 3986은 다음과 같이 일반 URI 구문을 정의합니다.
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
1. URI 구성요소
API 내에서 사용되는 URL의 구조는 소비자에게 의미가 있어야 하며, URL은 이해 가능성과 사용성을 높이기 위해 예측 가능한 계층적 구조를 따라야 합니다.
URL은 다음과 같이 표준 명명 규칙을 따라야 합니다.
https://gw.api.gov.au/namespace/project-name/v1/collection?fields=startDate,endDate
\___/ \___________/ \__________________________________/ \______________________/
| | | |
scheme authority path query
2. URI 최대 길이
Path 및 Query를 포함한 총 URI는 쉼표, 밑줄, 물음표, 하이픈, 더하기 또는 슬래시와 같은 형식 코드를 포함하여 길이가 2000자를 초과하면 안 됩니다.
- Rule #1 - 후행 전달 슬래시(/)를 URI에 포함하지 않습니다.
이 규칙은 URI 경로 내의 마지막 문자인 순방향 슬래시(/)가 의미 값을 추가하지 않아 혼동을 일으킬 수 있으므로 따라야 하는 가장 중요한 규칙 중 하나입니다. REST API는 후행 슬래시를 기대해서는 안 되며 클라이언트에 제공하는 링크에 이러한 규칙을 포함해서는 안 됩니다.
많은 웹 구성 요소와 프레임워크는 다음 두 개의 URI를 동등하게 취급합니다.
1. http://api.canvas.com/shapes/
2. http://api.canvas.com/shapes
그러나 URI 내의 모든 문자는 리소스 고유 ID로 계산됩니다. 서로 다른 두 개의 URI는 서로 다른 두 개의 리소스에 매핑됩니다. URI가 서로 다른 경우에는 리소스도 매핑되고, 그 반대의 경우에는 리소스도 매핑됩니다. 따라서, REST API는 깨끗한 URI를 생성하고 통신해야 하며, 리소스를 부정확하게 식별하려는 클라이언트의 시도를 허용하지 않아야 합니다.
- Rule #2 - 계층 관계를 나타내려면 슬래시 구분자(/)를 사용해야 합니다.
순방향 슬래시(/) 문자는 리소스 간의 계층적 관계를 나타내기 위해 URI의 경로 부분에서 사용됩니다.
1. http://api.canvas.com/shapes/polygons/quadrilaterals/squares
- Rule #3 - URI 가독성을 향상시키기 위해서는 하이픈(-)을 사용해야 합니다.
URI를 사람들이 스캔하고 해석하기 쉽도록 하려면 하이픈(-) 문자를 사용하여 긴 경로 세그먼트의 이름 가독성을 높입니다. 영어의 공백이나 하이픈을 사용하는 곳에서는 URI의 하이픈을 사용해야 합니다.
1. http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post
- Rule #4 - URI에는 밑줄(_)을 사용하면 안 됩니다.
텍스트 뷰어 응용 프로그램(브라우저, 편집기 등)은 클릭 가능하다는 시각적 단서를 제공하기 위해 URI에 밑줄을 긋는 경우가 많습니다. 응용 프로그램의 글꼴에 따라 밑줄 문자가 부분적으로 가려지거나 이 밑줄로 완전히 가려질 수 있습니다. 이러한 혼란을 방지하려면 밑줄 대신 하이픈(-)을 사용합니다.
* Query String > Parameters
1. Query string의 Literals/expressions는 밑줄(_)을 사용하여 구분해야 합니다.
2. Query parameters는 percent-encoding 되어야 합니다.
3. AWS에서 Query parameters가 정규식 ^[a-zA-Z0-9._$]+$와 일치해야 합니다.
4. Query parameters는 문자로 시작해야 하며 필드 이름에 사용되는 대소문자 표준과 일치하는 camelCase 또는 snake_case여야 합니다.
5. Query parameters는 선택 사항이어야 합니다.
6. Query parameters에 URL이 안전하지 않은 문자가 포함되면 안 됩니다.
- Rule #5 - URI는 소문자를 선호해야 합니다.
대문자가 문제를 일으킬 수 있으므로 URI 경로에서 소문자를 선호합니다. RFC 3986은 Scheme과 Host 구성 요소를 제외하고 URI를 대소문자를 구분하는 것으로 정의합니다.
예를 들어, 아래 URI는 괜찮습니다.
1. http://api.example.com/my-folder/my-doc
2. HTTP://API.EXAME.COM/my-folder/my-doc
URI 포맷 사양(RFC 3986)은 이 URI를 URI #1과 동일한 것으로 간주합니다.
3. http://api.example.com/My-Folder/my-doc
이 URI는 URI 1 및 2와 동일하지 않으므로 불필요한 혼동을 초래할 수 있습니다.
- Rule #6 - 파일 확장명은 URI에 포함되지 않아야 합니다.
웹에서 마침표(.) 문자는 URI의 파일 이름과 확장자 부분을 구분하는 데 일반적으로 사용됩니다. REST API는 메시지 엔티티 본문의 형식을 나타내기 위해 URI에 인공 파일 확장자를 포함해서는 안 되며, 대신 본문의 내용을 처리하는 방법을 결정하기 위해 Content-Type 헤더를 통해 전달되는 미디어 유형에 의존해야 합니다.
간단한 keep-it-simple 규칙이 여기에 적용됩니다. 내부 문법학자가 리소스의 단일 인스턴스를 복수를 사용하여 설명하는 것은 잘못이라고 하겠지만 실용적인 답은 URI 형식을 일관되게 유지하고 항상 복수를 사용하는 것입니다.
1. http://api.college.com/students/3248234/courses
ID가 3248234인 학생이 학습한 모든 과정의 목록을 검색합니다.
2. http://api.college.com/students/3248234/courses/physics
ID가 3248234인 학생의 과정 물리학을 검색합니다.
5가지 기본 REST API 설계 지침
7 Rules for REST API URI Design
5 Basic REST API Design Guidelines
Australian Government - API Design Standard