REST API 명세 (명명 규칙)

서버와 클라이언트의 개발자가 따로 있는 경우에는 rest api 명세를 먼저 작성하는 경우가 많다.

어느정도 기획 회의를 거쳐서, 간단한 화면 구성도를 보게되면 서버 개발자가 api 명세를 먼저 작성한다.

 

백엔드 개발자가 spring 을 이용하면 보통 swagger 로 api 명세를 작성하지만,

백엔드 개발자가 여러명이고 실제 개발을 시작하기 전에는 api 명세를 같이 작성하는데,

이때 api 명세 툴은 postman, gitbook 등을 이용할 수 있다.

 

그리고 api 는 보통 RESTful 하게 만드는데, REST 란 Representational State Transfer 의 약자로 자원의 이름을 구분해서 자원의 상태를 주고 받는것을 의미한다.

 

restful 하게 api 를 만들기 위한 몇가지 명명규칙이 있다.

 

1. 동사가 아닌 명사를 사용한다.
2. 대문자 보다는 소문자를 사용한다.
3. 단수형이 아닌 복수형을 사용한다.
4. 자원의 이름이 긴 경우에는 하이픈(”-”) 을 이용한다.
5. 자원을 조작하는 행위(cud) 는 http method 를 이용한다.
6. 자원을 식별하는 아이디값은 url 에 포함하지만, 특정 행위(정렬, 검색 등) 를 위한 값은 쿼리 파라미터를 이용한다.
7. 계층 관계를 나타낼때는 슬래쉬(”/”) 로 나눈다.
8. url 의 마지막에는 슬래쉬(”/”) 를 포함하지 않는다.
9. 확장자는 표시하지 않는다.