Google Cloud API Design Guide - Custom Method 정리

REST API 를 설계할 때 Transaction을 위한 REST API설계가 항상 고민이었다...

 

그래서 구글 클라우드 API의 설계 가이드 내용을 그대로 가져와 본다....

 

다음 부터는 구글 클라우드 API의 설계 가이드 이다.

 

https://cloud.google.com/apis/design/custom_methods

커스텀 메서드  |  Cloud API  |  Google Cloud

 

리소스 중심 디자인

 

REST API - 개별적으로 주소 지정이 가능한 리소스(API의 명사)의 컬렉션으로 모델링 된다.

리소스는 리소스 이름으로 참조 되며, 적은 수의 메서드 집합(동사 또는 작업으로 알려짐)을 통해 조작됩니다.

 

 

표준 메서드 - List, Get, Create, Update, Delete

 

데이터 베이스 트랜잭션과 같이 표준 메서드로 쉽게 매핑되지 않는 기능은

커스텀 메서드(커스텀 통사 또는 커스텀 작업)으로 사용할 수도 있다.

 

커스텀 메서드는 다음과 같이 일반적인 HTTP 매핑을 사용해야 한다.

https://service.name/v1/some/resource/name:customVerb

커스텀 동사를 리소스 이름과 구분할 때 /가 아닌 :를 사용하는 이유는 임의 경로를 지원하기 때문입니다. 예를 들어 파일 삭제 취소는 POST /files/a/long/file/name:undelete로 매핑될 수 있습니다.

 

 

• 커스텀 메서드는 가장 유연한 시맨틱스를 가지고 있기 때문에 가능하면 GET을 사용할 수 있는 대체 get 또는 list의 역할을 하는 메서드를 제외하고 HTTP POST 동사를 사용해야 합니다. (자세한 내용은 세 번째 항목 참조)
• 커스텀 메서드는 HTTP PATCH를 사용해서는 안 되지만 다른 HTTP 동사는 사용할 수 있습니다. 이러한 경우 메서드는 해당하는 동사에 맞는 표준 HTTP 시맨틱스를 따라야 합니다.
• 특히 HTTP GET을 사용하는 커스텀 메서드는 반드시 멱등성을 가져야 하며 부작용이 없어야 합니다. 예를 들어 리소스에 대해 특별한 뷰를 구현하는 커스텀 메서드는 HTTP GET을 사용해야 합니다.
• 커스텀 메서드가 연결되는 리소스 또는 컬렉션의 리소스 이름을 수신하는 요청 메시지 필드는 URL 경로에 매핑되어야 합니다.
• URL 경로는 콜론에 이어 커스텀 동사로 구성되는 서픽스로 끝나야 합니다.
• 커스텀 메서드에 사용되는 HTTP 동사가 HTTP 요청 본문을 허용하는 경우(POST, PUT, PATCH, 커스텀 HTTP 동사에 적용됨) 이러한 커스텀 메서드의 HTTP 구성은 body: "*" 절을 사용해야 하며 나머지 모든 요청 메시지 필드는 HTTP 요청 본문으로 매핑되어야 합니다.
• 커스텀 메서드에 사용되는 HTTP 동사가 HTTP 요청 본문을 허용하지 않는 경우(GET, DELETE), 해당하는 메서드의 HTTP 구성이 body 절을 사용해서는 안 되며 나머지 모든 요청 메시지는 URL 쿼리 매개변수로 매핑되어야 합니다.

 

공통 커스텀 메서드

메서드 이름	커스텀 동사	HTTP 동사	참고사항
Cancel	:cancel	POST	대기 중인 작업(예: operations.cancel)을 취소합니다.
BatchGet	:batchGet	GET	다수의 리소스를 일괄 방식으로 가져옵니다.
Move	:move	POST	리소스를 상위 수준에서 다른 수준으로 이동합니다.(예: folders.move)
Search	:search	GET	List 시맨틱스를 따르지 않는 데이터를 가져오기 위한 List의 대안입니다.
Undelete	:undelete	POST	이전에 삭제했던 리소스를 복원합니다.(예: services.undelete). 권장 보장 기간은 30일 입니다.