AIP-130

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

Categories of Methods

The following enumerates multiple categories of methods that exist, often grouped up under some object (e.g. collection or resource) that the method operates upon.

Category Name Related AIPs Declarative client integration CLI / UI integration SDK integration
Standard Methods
Standard collection methods: operate on a collection of resources (List or Create). AIP-121, AIP-132, AIP-133 automatable automatable automatable
Standard resource methods: fetch or mutate a single resource (Get, Update, Delete). AIP-121, AIP-131, AIP-134, AIP-135 automatable automatable automatable
Batch resource methods: fetch or mutate multiple resources in a collection by name. AIP-231, AIP-233, AIP-234, AIP-235 may be used to optimize queries automatable automatable
Aggregated list methods: fetch or mutate multiple resources of the same type across multiple collections. AIP-159 not useful nor automatable automatable automatable
Custom Fetch Methods
Custom collection fetch methods: fetch information across a collection that cannot be expressed via a standard method. AIP-136 handwritten automatable automatable
Custom resource fetch methods: fetch information for a single resource that cannot be expressed via a standard method. AIP-136 handwritten automatable automatable
Custom Mutation Methods
Backing up a resource: storing a copy of a resource at a particular point in time. AIP-162 unused or handwritten automatable automatable
Restoring a resource: setting a resource to a version from a particular point in time. AIP-162 unused or handwritten automatable automatable
Renaming a resource: modify the resource's name or id while preserving configuration and data. AIP-136 unused or handwritten automatable automatable
Custom collection mutation methods: perform an imperative operation referencing a collection that may mutate one or more resources within that collection in fashion that cannot be easily achieved by standard methods (e.g. state transitions). AIP-136 unused or handwritten automatable automatable
Custom resource mutation methods: perform an imperative operation on a resource that may mutate it in a way a standard method cannot (e.g. state transitions). AIP-136 unused or handwritten automatable automatable
Misc Custom Methods
Stateless Methods: a method that has no permanent effect on any data within the API (e.g. translating text) AIP-136 unused or handwritten automatable automatable
None of the above
Streaming methods: methods that communicate via client, server, or bi-directional streams. handwritten handwritten automatable

Choosing a method category

While designing a method, API authors should choose from the defined categories in the following order:

  1. Standard methods (on collections and resources)
  2. Standard batch or aggregate methods
  3. Custom methods (on collections, resources, or stateless)
  4. Streaming methods

Rationale

Resource-oriented standard and custom methods are recommended first, as they can be expressed in the widest variety of clients (Declarative clients, CLIs, UIs, and so on), and offer the most uniform experience that allows users to apply their knowledge of one API to another.

If a standard method is unsuitable, then custom methods (that are mounted to a resource or collection) 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. Although mutative custom methods are not uniform enough to have a automated integration with exclusively resource-oriented clients such as Declarative clients, they are still a pattern that can easily recognized by CLIs, UIs, and SDKs.

If one cannot express their APIs in a resource-oriented fashion at all, then the operation falls in a category where the lack of uniformity makes it difficult for any client aside from SDKs to model the operation. This category is preferred last due to the fact that a user cannot rely on their knowledge of similar APIs, as well as the issue that integration with many clients will likely have to be hand-written.

Changelog

  • 2023-09-05: Update to approved.