[Network] REST API - Naming Convention, Best Practice

TL;DR

GET http://api.example.com/v1/store/employees/{emp-id}
POST http://api.example.com/v1/store/employees

 

동사 대신 리소스를 나타내는 명사 사용

항상 URI가 동사를 사용하는 대신 리소스를 지정하는 명사로 명명되었는지 확인해야 한다. URI는 어떤 CRUD(Create, Read, Update, Delete) 작업도 나타내지 않아야 한다. CRUD는 HTTP Method(GET, POST...)로 표현한다. 또한 동사-명사 조합 (하이픈, 스네이크 케이스, 카멜 케이스)을 피해야 한다.

나쁜 예:

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}✅

 

 

리소스에 복수형 명사 사용

가능한 경우 복수형을 사용하되 싱글톤 리소스^[각주:1]인 경우에는 단수를 사용한다.

나쁜 예 (일반 및 싱글톤 리소스):

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✅

 

하이픈(-)을 사용하여 URI 가독성 향상

언더스코어를 사용하지 않는다. 단어를 하이픈으로 구분하면 당신과 다른 사람이 이를 쉽게 해석할 수 있다. 긴 경로 세그먼트 URI의 경우 더 사용자 친화적이다.

Hypen을 사용하는 이유는 Shift키를 누르지 않고 입력할 수 있어서 더 편리하기 때문이다

나쁜 예:

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✅

 

슬래시(/)를 사용하여 계층을 표시하되 마지막에는 슬래시(/)를 붙이지 않기

슬래시는 개별 리소스와 컬렉션 간의 계층을 보여 주기 위해 사용된다.

나쁜 예:

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

좋은 예:

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

 

파일 확장자 사용 피하기

파일 확장자는 불필요하며 URI의 길이와 복잡성을 높인다.

REST Architectural Contstraint를 고려한 규칙인 것 같다

나쁜 예:

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✅

 

API 버전 관리

항상 API를 버전별로 관리한다. API를 버전화하면 기존 API를 근본적으로 변경하지 않고도 업데이트 URL를 제공할 수 있다. 업데이트된 API 버전을 사용할 수 있는 지 사용자에게 알릴 수 있다.

http://api.example.com/v1/store/employees/{emp-id}

 

Breaking Change를 도입할 때 /v2를 사용하여 기존 버전의 변경을 피할 수 있는 장점이 있다.

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

 

Query Component를 사용하여 URI 컬렉션^[각주:2] 필터링

특정 리소스 속성에 따라 리소스 그룹을 정렬, 필터링 또는 제한해야 하는 요구 사항이 자주 발생한다. 추가 API를 생성하는 대신 리소스 컬렉션 API에서 정렬, 필터링 및 페이지네이션을 활성화하고 입력 매개변수를 쿼리 매개변수로 제공하여 이 요구 사항을 충족시킬 수 있다.

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

 

CRUD 예시

• GET — 직원 ID가 8345인 직원 읽기

example.com/employees/8345

• POST— 직원 생성

example.com/employees

• PUT— 직원 ID가 8345인 직원 업데이트

example.com/employees/8345

• DELETE — 직원 ID가 8345인 직원 삭제

example.com/employees/8345

 

출처

https://medium.com/@nadinCodeHat/rest-api-naming-conventions-and-best-practices-1c4e781eb6a5

 

1. DB에서 하나의 인스턴스만을 갖는 리소스. 설정 파일 등. [본문으로]
2. REST API에서 여러 리소스의 모음. 예를 들면 제품 목록. [본문으로]