REST API 컨벤션 정리

1. 복수 형태를 사용하자

GET: /users
POST: /users
PUT: /users/12
DELETE: /users/12

DB의 유저 Table을 생각하면 보다 쉽게 이해가 된다.
유저 array를 받아오는 요청은 여러 유저 정보를 받아오는 것이니 users가 자연스럽다. (GET: /users)
유저를 생성하는 것도 유저 array에 하나의 유저를 추가하는 것이기 /users에 요청을 보낸다고 이해하면 된다. (POST: /users)
특정 id의 유저를 받아오는 것도 유저 array 중에서 고르는 것이기에 /users/:id가 꽤나 자연스럽다.

몇몇 글을 살펴보면 복수를 선호하지만 단수를 쓰는 것도 큰 상관은 없다는 의견들이 많아. 하지만 모두 공통적으로 혼합해서 사용하는 것은 지양한다.

2. 명사 형태를 사용하자

여러가지 이유가 있지만, 동사를 사용하면 같은 리소스에 대한 동작도 이름이 매우 달라지게 된다. 반면 명사를 사용하면 보다 api를 깔끔하게 관리할 수 있다.

GET:  /getUsers     --> GET: /users
POST: /createUser   --> POST: /users
PUT:  /updateUser/1   --> PUT: /users/1

 

3. 하이픈 (-), kebab-case를 사용하자

주소에서 표현하는 리소스가 길어지는 경우, 하이픈(-)을 이용해서 구분하는 것이 가독성에 좋다.

GET: /devicemanagement/manageddevices   --> GET: /device-management/managed-devices

밑줄(언더스코어, _)을 사용하여 구분할 수도 있지만, 브라우저가 자체적으로 url 주소에 대해서는 자동적으로 밑줄을 표시하는 경우가 있다. 이러한 경우 url에 밑줄이 포함 된다면, 폰트에 따라서 밑줄이 빈 칸 처럼 보일 수도 있게 된다.

4. 소문자를 사용하자

일반적으로 URI 경로에서는 소문자를 사용하는 편이다. URL에서 프로토콜과 호스트 주소는 대소문자를 구분하지 않지만, 리소스 경로 부분은 운영체제 등에 따라 구분하는 경우가 있다. 윈도우 운영체제라면 디렉터리나 파일 이름에서 대소문자를 구분하지 않으나, 리눅스 혹은 유닉스 계절의 서버라면 대소문자를 구분한다.
그러니 혹시 모를 상황을 대비하고 일관성을 유지하기 위해서라도 소문자로 통일하는 것이 더 선호 된다.

5. 컬렉션 필터링: URL 쿼리를 이용하자

api를 설계하다보면 필터링이 필요한 경우가 많이 존재한다. 이런 경우에는 새로운 api를 만들기보다는 쿼리 파라미터를 활용하는 것이 좋다. 동일한 테이블을 타겟으로 하는 api는 하나로 통일되는 것이 장려된다는 의미이다.
이는 필터링뿐만 아니라 정렬이나 페이지네이션 등에서도 마찬가지이다.

/users/region/ko               --> /users?region=ko
/users/gender/femail           --> /users?gender=female
/users/region/ko/gender/female --> /users?region=ko&gender=female