[API] REST - 자원에 대한 식별: URI 표기법

자원에 대한 식별 (identification of resources)

 REST의 조건 중 '자원에 대한 식별'은 다루고자 하는 자원에 특정한 이름을 부여함으로서 그 자원을 식별할 수 있어야 함을 의미합니다. 웹 API는 URI를 사용하여 자원에 대한 식별을 하고 있습니다. 이를 위해서는 URI 안에 자원에 대한 명시가 있어야 하고, 그 자원을 식별할 수 있는 고유한 ID(식별자) 또한 URI에 포함하여야 합니다.

 

 아래에 '자원에 대한 식별'를 위한 URI의 표기 방법을 정리하였습니다.

1. 명사 사용

URI는 특정 동작을 수행할 대상을 나타낸 명령어입니다. 때문에 일반적으로 URI는 함수와 달리 명사형으로 자원을 나타냅니다.

# (x)
/get-member-list
/create-new-article

# (o)
/member-list
/articles

2. 단수/복수 구분

자원을 명사형으로 사용하기 때문에, 대상의 개수에 따라 단수와 복수형으로 구분하는 것이 좋습니다.

/members	# /(복수)
/members/1	# /(복수)/(단수)
/key		# /(단수)

3. 계층 표현에서 슬래시('/') 사용

자원들 사이의 계층 표현은 슬래시('/')를 사용합니다. 단, 마지막 계층의 자원 뒤에는 슬래시('/')를 붙이지 않습니다.

# (x)
/articles/1/comments/

# (o)
/articles/1/comments

4. 소문자로 작성

대문자를 혼용하는 카멜케이스(CamelCase) 를 사용하지 않고, 모두 소문자로 작성합니다.

띄어쓰기가 필요한 경우, 하이픈('-')을 사용합니다.

# (x)
/articles/topVoted

# (o)
/articles/top-voted

5. 확장자 포함하지 않음

 파일의 확장자는 자원의 식별자를 뜻하는 것인지, 그 파일 자체를 뜻하는 것인지 혼동을 줄 수 있기 때문에 기입하지 않습니다. 만약 HTML / JSON과 같은 미디어 타입을 강조하고 싶은 경우 Content-Type 헤더를 사용하여 전달합니다.

# (x)
/articles.html
/members.json

# (o)
/articles
/members