[CS] RESTful API 명명법

REST(Representational State Tranfer) API는 URI를 통해 자원을 표시해야하며, HTTP Method를 이용하여 자원의 행위를 규정한다. 그렇기 때문에 REST API 설계시, 이 두가지 항목이 제일 중요시하게 된다. 이번 글에서는 RESTful API 명명 규치에 대해 다룬다.

 

⊙ REST API 명명 규칙

1. 후행 슬래쉬(Back Slash "/")는 마지막에 포함되지 않는다.

슬래쉬는 각 계층적 관계를 표현한다. 후에 다른 계층이 존재하지 않을 경우, 쓰지 않는 것이 원칙이다. 후행 쓸래쉬는 의미가 전혀 없을 뿐만 아니라 Front-End 개발자에게 혼란을 야기하기 때문에 자양한다.

https://www.naver.com/

https://www.naver.com

두 URI는 접속했을때 같은 웹페이지로 연결되지만, URI는 서로 다른 리소스로 매핑된다.

Ex) http://localhost:8080/web/api

 

2. 언더바(Under Bar "_") 대신에 하이픈(Hyphen "-")을 사용한다.

언더바(Under Bar "_")를 사용할 경우, 사용하는 프로그램의 글자 폰트에 따라 밑줄 처리에 의해 부분적으로 가려지거나 안 보일수가 있어 혼란을 야기한다. 따라서 사람들에게 더 쉽게 읽히게 하기 위해 하이픈(Hyphen "-")으로 단어를 구분한다. 

Ex) http://localhost:8080/web/user/user-info

 

3. 소문자를 이용하여 URI를 구성한다.

대문자를 이용할 경우, 문제가 발생하는 경우가 있어 소문자를 이용한다.

Ex) http://localhost:8080/web/uesr/post

 

4. 행위를 표현하지 않는다.

행위(Create, Read, Update, Delete)는  URI내에 포함하지 않고 Method를 이용하여 전달한다.

Ex)

POST http://localhost:8080/web/user/delete-post

DELETE http://localhost:8080/web/user/post 

 

 

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

Body 형식을 나타내기 위해 파일 확장자를 URI내에 포함하지 않는다. Accept Header를 이용하여 형식을 선택하고, 쉬운 링크와 디버깅을 위해 Query Param 또는 Path Param을 이용하여 타입을 선택한다.

Ex) http://localhost:8080/web/user/user-info

 

6. 복수 명사를 이용하여 만든다.

전달하고자 하는 URI를 간단하고 직관적으로 전달하기 위해, 명사를 이용하여 구성한다. 또한, 복수형으로 표현하여 직관성을 높인다.

Ex) http://localhost:8080/web/items/price

 

⊙ 정리

이렇듯 RESTful API를 설계하는데 체계적인 명명법이 존재하는 이유는 URI의 이해력을 높이고, 예측 가능해야하며, 계층 구조적이기 위함이다. 이러한 명명법을 통해 명확한 REST API를 설계하고 API를 호출하는 Front-End 개발자와 원활하게 통신할 수 있다. 위의 규칙을 통해 더욱 명료하고 강력한 API를 구축할 수 있다.