RESTful API URL 설계

프론트엔드없이 시작된 React 프로젝트에 투입되게 되었다.
그러다보니 Url이 규칙없이 설계된 모습을 보게 되었고 나 또한 오랜만에 프로젝트를 하다보니 Url 주소를 어떻게 지어야 좋을지 고민을 하게 되었다.
해당 프로젝트에서는 RESTful API를 사용하고 있으니, 이에 맞게 RESTful URL을 사용하면 좋을 것 같아 찾아보게 되었다.

RESTful API URL 작성 규칙

1. 마지막에 / 를 포함하지 않는다.

/는 계층을 구분하는 것으로, 마지막에는 사용하지 않는다.

👎 Bad

http://api.test.com/users/

👍 Good

http://api.test.com/users

2. _(underbar) 대신 -(dash)를 사용한다.

-(dash)의 사용도 최소한으로 설계한다. 정확안 의미나 표현을 위해 단어의 결합이 불가피한 경우-(dash)를 사용한다.

👎 Bad

http://api.test.com/users/post_comments

👍 Good

http://api.test.com/users/post-comments

3. 소문자를 사용한다.

👎 Bad

http://api.test.com/users/postComments

👍 Good

http://api.test.com/users/post-comments

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

행위는 URL 대신 HTTP Methods(POST, GET, PUT, DELETE...)를 써서 전달한다.

👎 Bad

http://api.test.com/users/1/delete-post/1

👍 Good

http://api.test.com/users/posts/1

5. 가급적 전달하고자하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우는 예외적으로 동사를 허용한다.

컨트롤 자원(Control Resource): RESTful API에서 특정 동작을 수행하는 엔드포인트

보통은 명사를 사용해서 자원을 표현하지만, 일반적인 CRUD외에 특정한 동작을 수행하는 경우에는 예외적으로 동사(기본형)를 사용하기도 한다.

👎 Bad

http://api.test.com/posts/duplicating

👍 Good

http://api.test.com/posts/duplicate

6. 파일 확장자는 URL에 포함시키지 않는다.

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URL안에 포함시키지 않는다. 대신 Accept header를 사용한다.

👎 Bad

http://api.test.com/users/photo.jpg

👍 Good

GET http://api.test.com/users/post-comments
HTTP/1.1 Host: restapi.example.com Accept: image/jpg

출처
https://library.gabia.com/contents/8339/
https://devuna.tistory.com/79