IPA-103: Methods

An API is composed of one or more methods, which represent a specific operation that a service can perform on behalf of the consumer.

State

Adopt

Guidance

• API authors should choose from the defined categories in the following order:
  • Standard methods (on collections and resources)
  • Custom methods (on collections, resources, or stateless)
• Standard methods must not cause side effects
  • In such scenarios where a side effect is necessary, a custom method should be used
• Standard methods must guarantee atomicity
  • In cases where atomicity cannot be guaranteed, consider in the following order:
    • A new sub-resource with the appropriate methods
    • A singleton-resource for the corresponding section
    • Custom methods, for example, an Add or Remove operation for repeated fields

If a standard method is unsuitable, then custom methods offer a lesser, but still valuable level of consistency, helping the user reason about the scope of the action and the object whose configuration is read to inform that action.

Selecting a custom method may be valuable for:

• State management of a resource since they usually carry side effects
• If atomic modifications are required when adding or removing from repeated fields

Naming

• The method name is the Operation ID (operationId) in the OpenAPI Specification
• Operation IDs must be unique
• Operation IDs must be in camelCase