커스텀 메서드란?
- 5가지 표준 메서드(get, list, create, update, delete)를 제외한 api 메서드
- 표준 메서드를 통해 쉽게 표현할 수 있는 경우에만 사용되어야 함
- 리소스, 컬렉션, 서비스와 연결될 수 있음
- 임의 요청을 사용하여 임의 응답을 반환할 수 있고, 스트리밍 요청 및 응답도 지원
특징
예시 : https://service.name/v1/some/resource/name:customVerb
- 커스텀 동사를 리소스와 구분할 때 임의의 경로를 지원하기 때문에 :(콜론) 사용
- 가장 유영한 시멘틱을 갖고 있기 때문에, Get을 사용할 수 있는 대체 Get 또는 list의 역할을 하는 메서드를 제외하곤 http post 동사를 사용해야 함
- http patch를 사용하면 안되지만, 다른 http 동사는 사용 가능. 이럴 경우의 메소드는 해당하는 동사에 맞는 표중 http 시멘틱스를 따라야 함
- http get 을 사용하는 커스텀 메서드는 반드시 멱등성을 가져야한다.(*멱등성 : 동일한 요청을 한 번 보내는 것과 여러번 보내는 것이 같은 효과를 지님)
- 커스텀 메소드가 연결되는 리소스, 컬렉션의 리소스 이름을 수신하는 요청 메시지 필드는 URL 경로에 매핑되어야 하나.
- 커스텀 메소드에서 사용되는 http 동사가 http 요청 본문을 허용하는 경우(
post
, put
, patch
, 커스텀 http 동사에 적용됨),
커스텀 메서드의 http 구성은 body:"*"
절을 사용해야 하며, 나머지 모든 요청 메세지 필드는 http 요청 본문으로 매피되어야 한다.
- 반대로 http 요청 본문을 허용하지 않는 경우(
delete
, get
), 해당하는 메소드의 http 구성이 body절을 사용해선 안되고, 나머지 모든 요청 메세지는 URL 쿼리 매개변수로 매핑되어야 한다.
공통 커스텀 메서드
google Cloud 커스텀 메서드