REST API Naming Convention 정리

본 글은 REST API Naming Conventions and Best Practices을 읽고 정리한 글이다

Intro

• API 명세서를 작성하기 전, 팀원들과 협업하기위해 URI naming에 대한 convention을 토대로 적용할 필요성을 느꼈다. REST API는 data의 표현을 중시하기에 적절한 naming은 API를 더 직관적으로 이해할 수 있도록 도울 수 있기 때문이다. 따라서 적절한 naming convention에 대해 정리해보았다.
  
  

1. 동사 대신 명사를 사용하라

• URI는 특정한 resource(data)를 의미해야하며 CRUD와 같은 operation을 의미해서는 안된다(이미 HTTP method들이 API의 기능을 대변하고 있다). 또한 snake case, camel case와 같은 verb-noun combination의 사용을 지양해야한다.

http://api.example.com/v1/store/CreateItems/{item-id}❌
http://api.example.com/v1/store/getEmployees/{emp-id}❌
http://api.example.com/v1/store/update-prices/{price-id}❌
http://api.example.com/v1/store/deleteOrders/{order-id}❌

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}✅
http://api.example.com/v1/store/prices/{price-id}✅
http://api.example.com/v1/store/orders/{order-id}✅

2. 다수의 resource에 대해서는 복수형을 이용하라

• singleton resource가 아니라면 복수형을 이용하라.

http://api.example.com/v1/store/item/{item-id}❌
http://api.example.com/v1/store/employee/{emp-id}/address❌

http://api.example.com/v1/store/items/{item-id}✅
http://api.example.com/v1/store/employees/{emp-id}/address✅

3. hyphen을 통해 가독성을 높여라

• 단어간 분리시킬때는 underscore를 이용하지 말고 hyphen을 이용하여 가독성을 높일 수 있다.

http://api.example.com/v1/store/vendormanagement/{vendor-id}❌
http://api.example.com/v1/store/itemmanagement/{item-id}/producttype❌
http://api.example.com/v1/store/inventory_management❌

http://api.example.com/v1/store/vendor-management/{vendor-id}✅
http://api.example.com/v1/store/item-management/{item-id}/product-type✅
http://api.example.com/v1/store/inventory-management✅

4. slash(/)는 계층 분리에만 사용하라

• slash는 resource간의 계층 분리할때 사용하고, URI 맨 마지막에는 붙이지 않는다.

http://api.example.com/v1/store/items/❌

http://api.example.com/v1/store/items✅

5. 불필요한 파일 확장자를 명시하지 말라

http://api.example.com/v1/store/items.json❌
http://api.example.com/v1/store/products.xml❌

http://api.example.com/v1/store/items✅
http://api.example.com/v1/store/products✅

6. URI에 API version을 명시하라

• application을 업데이트 했을때, 기존의 URI에서 version부분만 바꿔줄 수 있게 함으로써 URI상의 큰 변화없이 반영할 수 있고, 사용자로 하여금 업데이트된 버전임을 쉽게 확인시켜줄 수 있다.

http://api.example.com/v1/store/items/{item-id}
http://api.example.com/v2/store/employees/{emp-id}/address

7. Query component를 통해 filtering하라

• sort, filter, pagination 등 resource에 대한 추가적인 처리가 필요한 경우, 이를 위한 추가적인 API를 만들지 말고 query parameter로 요청을 받을 수 있도록 API를 작성해야한다.

http://api.example.com/v1/store/items?group=124
http://api.example.com/v1/store/employees?department=IT&region=USA