URI 작성 규칙

REST의 '자원의 식별' 제약 조건은 접근하고자 하는 자원을 명시하고, 그 자원을 식별할 수 있어야 한다는 내용을 담고 있습니다. 웹에서는 URI를 사용하여 자원에 대한 식별을 하고 있는데요. URI에 제어하고자 하는 자원에 대해 명시하고, 그 자원을 식별할 수 있는 변하지 않는 ID과 같은 식별자를 URI에 포함하여야 합니다. REST의 제약 조건, '자원의 식별' 제약 조건을 지키도록 URI를 만들 수 있는 규칙들을 알아봅시다.

명사형 사용

URI는 동작(동사)을 가리키는 대신에, 자원(명사)을 가리켜야 합니다. 자원에는 속성이 있듯이, 명사는 동사가 가지지 않는 속성을 가지기 때문입니다.

Bad ❌

/get-member-list /create-new-member

Good ✅

/members /articles

반환(응답)하는 자원의 종류에 따라 단수형/복수형 사용하기

여러 개의 자원을 반환한다면 복수형, 단 1개의 자원을 반환한다면 단수형을 사용합니다.

/members # 멤버 목록 (복수형) /members/1 # 멤버 목록 중 (복수형), 1번 멤버 (단수형) /key # 1개의 키 (단수형)

계층 표현을 위하여, 슬래시(/) 사용

자원들 간의 계층 표현을 위해서 슬래시(/)를 사용합니다.

/articles /articles/1 /articles/1/comments /articles/1/comments/2

마지막 슬래시(/) 붙이지 않기

마지막에 붙는 슬래시를 트레일링 슬래시 (Trailing Slash)라고 합니다. 마지막 슬래시는 REST에서 어떠한 의미도 가지지 않기 때문에 혼동을 줄 수 있습니다. 따라서 붙이지 않습니다.

Bad ❌

/articles/1/comments/

Good ✅

/articles/1/comments

모두 소문자로 작성 & 띄어쓰기는 대시(-) 사용

언더스코어(_) 또는 카멜 케이스(CamelCase)는 가독성을 낮출 수 있기에 사용하지 않습니다. 띄어쓰기를 위한 대시(-)와 함께 소문자를 사용합니다.

Bad ❌

/articles/topVoted /articles/top_voted

Good ✅

/articles/top-voted

파일 확장자 포함하지 않기

파일 확장자는 특정 파일을 가리키는지, 아니면 자원의 식별자인지 헷갈릴 수 있기에 넣지 않습니다. 만약 HTML, JSON과 같은 미디어 타입을 강조하고 싶은 경우, Content-Type 헤더를 사용하여 전달합니다. Content-Type 헤더는 추후 레슨에서 더 알아보도록 할게요.

Bad ❌

/articles.html /members.json

Good ✅

/articles /members

목록에 필터가 필요할 경우, 쿼리 문자열을 사용

/articles/1/comments?sort=latest

URI에 동사 사용하지 않기

HTTP 메소드만으로도 충분히 해당 내용을 표현할 수 있기 때문에, URI에 불필요한 동사를 사용하지 않습니다. 여기서 HTTP 메소드가 무엇인지 지금은 자세히 알지 못해도 괜찮아요. 추후 레슨에서 다시 알아보겠습니다.

Bad ❌

/members/1/delete /members/2/update

Good ✅

DELETE /members/1 PUT /members/2

위의 규칙들은 직관적이고 명확한 URI, 그리고 REST의 '자원의 식별' 제약 조건을 지키기 위하여 제안된 것들인데요. 정말 많아 보이지만 자원의 '명시'와 '식별' 관점에서 본다면 그리 복잡한 내용을 담고 있지는 않을 거예요!

나아가 웹 서비스를 만들다 보면 이 모든 규칙을 완벽하게 지킬 수 없는 상황이 생길 수도 있습니다. 경우에 따라 API를 사용하는 클라이언트와의 약속이 더 우선시되는 경우도 있으니, 너무 규칙 자체에 얽매이지 않아도 괜찮습니다.