IPA-109: Custom Methods

Resource-oriented design uses custom methods to provide a means to express arbitrary actions that are difficult to model using only the standard methods.

State

Adopt

Guidance

• Custom methods should only be used for functionality that cannot be easily expressed via standard methods
  • Prefer standard methods if possible, due to their consistent semantics
• The name of the method should be a verb and may be followed by a noun
• The HTTP method must be GET or POST:
  • GET must be used for methods retrieving data or resource state.
  • POST must be used if the method has side effects or mutates resources or data
• Custom methods using the GET HTTP method must return a 200 OK response.
• The HTTP URI must use a colon(:) character followed by the custom method name
  • This aims to clearly distinguish between custom methods and other resources
  • The custom method name must be written in camelCase
• See Declarative-friendly resources for further guidance

Example

POST /groups/${groupId}/clusters/${clusterName}:pause
GET /groups/${groupId}/clusters:search
POST /groups/${groupId}/clusters/${clusterName}:addNode
POST /groups/${groupId}/clusters/${clusterName}:removeNode

Naming

• Operation ID must be unique
• Operation ID must be in camelCase
• Operation ID must start with the custom method verb
  • Derived from the path section delimited by the colon (:) character
• Operation ID should be followed by a noun or compound nouns
• The noun(s) in the Operation ID should be
  • The collection identifiers from the resource identifier in singular form
  • The custom method noun(s)
    • Derived from the path section delimited by the colon (:) character

Resource Identifier	Operation ID
/groups/${groupId}/clusters/${clusterName}:pause	pauseGroupCluster
/groups/${groupId}/clusters/${clusterName}:addNode	addGroupClusterNode
/groups/${groupId}/clusters:search	searchGroupClusters

Declarative-friendly resources

• Declarative-friendly resources must not use custom methods. To learn more, see IPA-127.
  • Custom methods require manual curation, implementation, and review for API tooling, which increases feature latency.
  • Declarative-friendly tools are unable to automatically determine what to do with them

tip

State transitions that carry side effects are usually good candidates for custom methods