RESTful API 설계 원칙 / 네이밍 규칙

RESTful API

클라이언트와 서버가 데이터를 주고받는 방식에 대한 아키텍처 스타일

 

RESTful API Naming

• 리소스 표현에 명사를 사용하라.
• 계층관계를 구분짓기 위해 슬래시(/)를 사용하라.
• URI 마지막에 슬래시를 붙이지 마라.
• 하이픈(-) 기호를 사용해 가독성을 높여라.
• 언더스코어를 사용하지 마라.
• 소문자만을 사용하라.

 

리소스 표현에 명사를 사용하라.

RESTful URI 가 가리키는 리소스는 수행되는 행위가 아니라 객체이다.

이 리소스가 어느 범주에 해당하는지 확인하고 그 범주에 맞는 네이밍 컨벤션을 일관되게 사용해야 한다.

 

☑️ 문서(Document)

• 단일 개념(파일 하나, 객체 인스턴스, 데이터베이스 row)
• 단수 사용(/device-management, /user-management)

http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin

 

☑️ 컬렉션(Collection)

• 서버가 관리하는 리소스 디렉터리
• 서버가 리소스의 URI를 생성하고 관리
• POST 기반 등록
• 복수 사용
• ex) 회원 관리 API

http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}

 

☑️ 스토어(Store)

• 클라이언트가 관리하는 자원 저장소
• 클라이언트가 리소스의 URI를 알고 관리
• PUT 기반 등록
• 복수 사용
• ex) 정적 컨텐츠 관리, 원격 파일 관리

http://api.example.com/files
http://api.example.com/files/new_file.txt

 

☑️ 컨트롤 URI 혹은 컨트롤러(Controller)

• 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
• 동사를 직접 사용
• 동사 사용
• ex) GET, POST 만 사용할 수 있는 HTTP FORM 의 경우 컨트롤 URI(동사) 를 사용

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play

 

일관성이 핵심이다.

일관된 리소스와 URI 형식을 사용하면 모호함이 최소화되고 가독성과 지속성이 극대화된다.

 

☑️ 계층 관계 표현을 위해 슬래시를 사용하라.

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}

 

☑️ 마지막 문자로 슬래시를 사용하지 마라.

http://api.example.com/device-management/managed-devices/ /* X */
http://api.example.com/device-management/managed-devices /* O */

 

☑️ 가독성을 위해 하이픈을 사용하라.

// More readable
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location
// Less readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation

 

☑️ 언더스코어는 사용하지 마라.

일부 브라우저나 화면에서는 `_`가 가려질 수 있기 때문에 혼란을 피하기 위해 `-`을 사용한다.

// More readable
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location
// More error prone
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location

 

☑️ 소문자를 사용하라.

스키마와 호스트에만 대소문자 구별이 없고, 이외에는 대소문자가 구별된다.

아래 3개의 URL은 대소문자 구별이 없다면 모두 동일하지만 1, 2번은 동일하고 3번은 같지 않다.

http://api.example.org/my-folder/my-doc // 1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc // 2
http://api.example.org/My-Folder/my-doc // 3

 

☑️ 파일 확장자를 사용하지 마라.

// X
http://api.example.com/device-management/managed-devices.xml
// O
http://api.example.com/device-management/managed-devices

 

CRUD 함수명을 사용하지 마라.

URI 는 어떠한 동작이 수행되는지를 가리키는게 아니라 리소스를 가리키는 것이다.

리소스에 대한 작업은 HTTP Method를 이용한다.

HTTP GET http://api.example.com/device-management/managed-devices/{id}  // Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  // Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  // Delete device for given Id

 

필터를 위해 쿼리 파라미터를 사용하라.

리소스에 대한 정렬, 필터링, 페이징은 신규 API 를 생성하지 않고 쿼리 파라미터를 활용하라.

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date

 

참고자료

https://restfulapi.net/resource-naming