[Web] 깔끔한 URL 패턴을 위한 REST Resource Naming Pattern Guide

안녕하세요. 개발자 Jindory입니다.

오늘은 REST API 개발시 URL 패턴을 정의하는 방법에 대해서 작성해보고자 합니다.

 

# 글 작성 이유

REST API 개발당시 url을 어떻게 설정해야하는지 기준이 명확하지 않아 제멋대로 개발하다보니 한번 정리해야할 필요성을 느껴서 자료들을 취합하여 정리해보고자 합니다.

---

# REST란?

Representational State Transfer의 약자이며, 다음과 같은 요소로 구성되어 있습니다.

• 자원(Resource) : URI
• 행위(Verb) : HTTP Method
• 표현(Representations)

즉 REST는 URI를 통해 자원(Resource)을 표시하고, HTTP Method를 기반으로 해당 자원의 행위를 규정하여 그 결과를 받는것을 말합니다.

---

1. URI Resource Modeling

Resource는 표현방식에 따라서 document, collection, store, controller 4가지로 나눌 수 있습니다.

1.1 Document

Document는 1개의 개체를 나타내는것으로 객체 인스턴스, DB의 record와 유사한 개념을 갖습니다.

REST에서는 리소스 집하(collection) 중 하나로 표현되어지며, 일반적으로 collection의 뒤에 '/'를 통해 구분합니다.

http://api.example.com/user/hobby/music/{id}
http://api.example.com/user/hobby/movie/{id}
http://api.example.com/user/study/programming/http-url/{id}

1.2 Collection

Collection은 단일 Resource(document)들의 묶음을 의미합니다. 복수형 단어를 사용합니다.

http://api.example.com/user/hobby/music/playlists
http://api.example.com/user/hobby/movie/watching
http://api.example.com/user/bank/accounts

1.3 Store

Collection과 비슷하게 Resource들을 모아두는 디렉토리의 개념이다. Collection과 다른점은 Client에 의해 관리되어진다는 점이다.

http://api.example.com/user/hobby/music/playlists
http://api.example.com/user/hobby/movie/watching
http://api.example.com/user/bank/accounts

1.4 Controller

Controller Resource는 Client에서 서버의 실행 가능한 function을 의미한다. RESTFUL 네이밍 가이드에 따르면 Controller의 경우 resource를 조작하는것이 아닌 직접 function을 실행하는 행위를 나타내기 위해 사용하므로, 동사를 사용해도 무방하다고 설명한다.

http://api.example.com/user/hobby/music/playlists/{id}/stop
http://api.example.com/user/hobby/music/playlist/{id}/start
http://api.example.com/user/study/programming/post/{id}/subscribe
http://api.example.com/user/bank/account/{id}/checkout

---

2. URI Path Naming Rule

2.1 마지막에 슬래쉬(/)를 포함하지 않아야 한다.

슬래쉬는 자원 간의 계층적 관계를 나타내기 위해서 사용합니다. 마지막에 슬래쉬만 오고 자원이 없는것은 의미가 전혀 없을 뿐만 아니라 혼란을 야기합니다. 따라서 마지막에는 슬래쉬를 사용하지 말아야 합니다. 

Bad

http://api.example.com/user/hobby/music/playlists/

Good

http://api.example.com/user/hobby/music/playlists

2.2 계층관계를 나타낼 때 슬래시 구분자를 사용한다.

슬래시문자는 URI의 경로 부분에서 자원 간의 계층적 관계를 나타내기 위해서 사용합니다. 아래의 URI는 user의 음악 리스트의 15번째 음악을 나타냅니다.

http://api.example.com/user/hobby/music/playlists/15

2.3 언더 스코어( _ ) 대신 하이픈( - )을 사용한다.

URI 설계시 하이픈(-) 사용도 최소한으로 설계해야한다. 하지만 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우 반드시 언더 스코어( _ )가 아닌 하이픈( - )을 사용해야합니다. 

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

이러한 혼란을 피하기 위해 언더바 문자보다는 하이픈 문자를 사용하는것을 권장합니다.

Bad

http://api.example.com/user/hobby/music/{1}/user_comments

Good

http://api.example.com/user/hobby/music/{1}/user-comments

2.4 URI 작성시 대문자가 아닌 소문자를 사용한다.

대문자는 때로 문제를 일으키는 경우가 있기 때문에 URI를 작성할 때는 소문자를 권장합니다. RFC3986은 체계 및 호스트 구성요소를 제외하고 URI를 대문자를 구분하여 정의합니다.

Bad

http://api.example.com/user/hobby/music/{1}/userComments

Good

http://api.example.com/user/hobby/music/{1}/user-comments

2.5 행위는 URI에 포함하지 않는다.

행위(HTTP Method)는 URL 대신 Method에 전달해야 합니다.(GET, POST, PUT, DELETE 등등)

Bad

POST http://api.example.com/user/study/programming/post-update/{id}

Good

PUT http://api.example.com/user/study/programming/post/{id}

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

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

Bad

http://api.example.com/user/my-info/profile/photo.jpg

Good

http://api.example.com/user/my-info/profile/photo

HTTP/1.1/ Host : api.example.com Accept : /image/jpg

---

이렇게 REST Resource Naming Pattern에 대해서 알아봤습니다.

 

혹시라도 정정할 내용이나 추가적으로 필요하신 정보가 있다면 댓글 남겨주시면 감사하겠습니다.

오늘도 Jindory 블로그에 방문해주셔서 감사합니다.

 

[ 참고 ]

https://restfulapi.net/resource-naming/

https://server-engineer.tistory.com/886?category=700671

https://changrea.io/Web/rest-api-design-1/