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.

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
  • A side effect specifically includes mutating client-owned fields of any resource other than the target of the request. The dependent mutation must be performed through the dependent resource's own endpoint; if the operation is fundamentally multi-resource by design, it must be modeled as a custom method per the rule above.
  • Side effects limited to read-only or effective values of another resource may occur in standard methods.
• 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

Response bodies

• Every endpoint must support a versioned JSON content type (e.g. application/vnd.atlas.YYYY-MM-DD+json), per IPA-900. Additional content types (e.g. +csv) may be offered alongside JSON.
• When a response body is returned as a JSON content type, it must be a JSON object with a fixed set of named properties at the root.
  • Top-level arrays, primitives, or objects with dynamic (unknown) keys at the root are prohibited because they cannot be consistently typed by schema-based clients and tooling.
  • Collections must be wrapped in an envelope object per IPA-110 (e.g. {"results": [...], "links": [...], "totalCount": 42}).

Naming

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