카테고리 없음

RESTful API URI 설계 규칙

arock 2022. 7. 8. 04:34
반응형

1. 후행 슬래시( / )는 URI에 포함하지 않는다.

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

Bad
http://api.canvas.com/shapes/

 

 

2. 소문자를 사용한다

  • URL에서 프로토콜과 호스트 주소에서 대소문자를 구분하지는 않으나,
  • 윈도우 운영체제는 디렉터리나 파일이름에서 대소문자를 구분하지 않고 리눅스 기반 서버는 대소문자를 구분한다.
  • 일관성을 유지하기 위해 소문자로 통일하는 것을 선호한다.
Good
1) http://api.example.com/my-folder/my-doc

2) HTTP://API.EXAMPLE.COM/my-folder/my-doc 
위의 URI는 괜찮습니다. 이 URI를 URI #1과 동일한 것으로 간주합니다.


Bad
3) http://api.example.com/My-Folder/my-doc
이 URI는 URI 1 및 2와 동일하지 않으므로 불필요한 혼동을 일으킬 수 있습니다.

 

 

3. 언더바(_) 대신 하이픈(-)을 사용한다.

  • 가독성을 높이기 위하여 하이픈(-)을 사용한다.
  • 텍스트 뷰어에서 언더바(_)를 사용할 경우 가려질 수 있어 사용을 지양한다.
Good
http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

Bad
http://api.example.com/blogs/guy-levin/posts/this_is_my_first_post

 

 

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

  • 슬래시( / )는 리소스 간의 계층적 관계를 나타내기 위해 URI의 경로 부분에 사용된다.
  • 행위는 포함하지 않는다.
  • 행위는 URL대신 Method를 사용하여 전달한다
Good
http://api.college.com/students

Bad
http://api.college.com/get-students
  • ex) 좋아하는 Device 목록
    REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용합니다.
  • 만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있습니다. 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.
    /리소스명/리소스 ID/관계가 있는 다른 리소스명

    GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

    GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)



5. 파일 확장자는 URI에 포함시키지 않는다.

  • 파일 확장자 정보는 Content-Type 헤더를 통해 전달합니다.
Good
http://api.college.com/students/3248234/courses/2005/fall

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

 

 

6.  리소스의 네이밍은 명사를 사용하되, 컨트롤 리소스를 의미하는 경우 예외적으로 동사를 허용한다.

GOOD
http://api.college.com/course/write

BAD
http://api.college.com/course/writing

 

 

7. URI에 작성되는 영어를 복수형으로 작성한다.

  • 하나의 인스턴스를 복수형으로 표시하는게 영어 문법적으로 맞지 않겟다고 생각할 수도 있지만 URI의 형식을 일관되게 복수형으로 사용하는 것이 통용되고 있는 방법이다.
ID가 3248234인 학생이 학습한 모든 과정 목록을 검색합니다. 
http://api.college.com/students/3248234/courses 

ID가 3248234인 학생의 코스 물리학을 검색합니다.
http://api.college.com/students/3248234/courses/physics
  • Collection : Document의 집합, DB에서 테이블이라 볼 수 있다.
  • Document : 문서 or 한 객체
  •  좀 더 직관적인 REST API를 위해서는 컬렉션과 도큐먼트를 사용할 때 단수 복수도 지켜준다면 좀 더 이해하기 쉬운 URI를 설계할 수 있습니다.
../restapi.example.com/sports/soccer
sports라는 컬렉션과 soccer라는 document로 표현되고 있다.

../restapi.example.com/sports/soccer/players/13
중요한 점은 컬렉션은 복수로 사용하고 있다는 점입니다.

 

 

8. 필터링이 필요한 경우 쿼리 파라미터를 사용한다.

Good
.../users?region=ko
.../users?gender=female
.../users?region=ko&gender=female


Bad
.../users/region/ko
.../users/gender/female
.../users/region/ko/gender/femal

 

 

 

참고 블로그

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

https://blog.pumpkin-raccoon.com/115

https://sanghaklee.tistory.com/57

https://velog.io/@couchcoding/%EA%B0%9C%EB%B0%9C-%EC%B4%88%EB%B3%B4%EB%A5%BC-%EC%9C%84%ED%95%9C-RESTful-API-%EC%84%A4%EA%B3%84-%EA%B0%80%EC%9D%B4%EB%93%9C

https://velog.io/@pjh612/REST-API-URI-%EA%B7%9C%EC%B9%99

 

반응형