[CS] Rest API: URL 디자인 가이드

Spring boot를 공부하면서 URL을 제멋대로 만들고 있었다는 걸 알게 되었다.

지난 REST API 포스팅에서 잠깐 다뤄졌던 내용인데 막연히 그렇구나 하고 넘어갔었는데 막상 실제로 사용하려니 어렴풋한 기억으로만 남아있기도 했고 그 중요성을 모르고 있었다.

 

따라서 이번에는 REST API 가이드에 맞는 URL 디자인을 복습 및 스터디해보려고 한다.

 

 

URL Rules

1. 슬래시(/)로 계층관계를 표현하고, URL의 마지막에 슬래시(/)을 포함하지 않는다.
2. 언더바(_) 대신 대쉬(-)를 사용한다.
3. 소문자를 사용한다.
4. 행위(method)는 URL에 포함하지 않는다.
5. 리소스명은 동사 대신 명사를 사용한다. 하지만, 컨트롤 자원을 의미하는 URL은 예외적으로 동사를 허용한다.
6. 파일 확장자는 포함하지 않는다.

 

1.  슬래시(/)로 계층관계를 표현하고, 마지막에 슬래시(/)을 포함하지 않는다.

http://test.com/users/name/banana/        (x)

http://test.com/users/name/banana         (o)

 

2. 언더바( _ ) 대신 대쉬(-)를 사용한다.

http://test.com/users/test_url         (x)

http://test.com/users/test-url         (o)

정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에만 대쉬(-)를 사용하지만, 최소한으로 설계한다.

이는 언더바(_)는 경우에 따라 보기 힘든 경우가 많기 때문에 가독성을 살리기 위함이다.

3. 소문자를 사용한다.

http://test.com/users/testUrl          (x)

http://test.com/users/test-url         (o)

대소문자에 따라 다른 리소스로 인식되기 때문에 URL 경로에 대문자 사용은 피해야한다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이라고 한다.

 

4. 행위(method)는 URL에 포함하지 않는다.

http://test.com/users/1/delete-name         (x)

http://test.com/users/1/name                    (o)

 

5. 리소스명은 동사 대신 명사를 사용한다. 하지만, 컨트롤 자원을 의미하는 URL은 예외적으로 동사를 허용한다.

http://test.com/users/duplicating           (x)
http://test.com/users/friend

http://test.com/users/duplicate              (o)

http://test.com/users/friends

RESTful URI는 동사가 아니라 명사 구성하는 것을 추천한다. 이유는 명사는 해당 Resource의 속성을 표현할 수 있지만 동사는 그렇지 못하기때문이다.

6. 파일 확장자는 포함하지 않는다.

http://test.com/users/profile.jpg         (x)

http://test.com/users/profile               (o)

 

---

참고

https://sanghaklee.tistory.com/57

RESTful API 설계 가이드

https://bcho.tistory.com/954

REST API 이해와 설계 - #2 API 설계 가이드

https://meetup.toast.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

https://sas-study.tistory.com/265

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