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). | resources, list, create | automatable | automatable | automatable |
| Standard resource methods: fetch or mutate a single resource (Get, Update, Delete). | resources, get, update, delete | automatable | automatable | automatable |
| Batch resource methods: fetch or mutate multiple resources in a collection by name. | batch-get, batch-create, batch-update, batch-delete | may be used to optimize queries | automatable | automatable |
| Aggregated list methods: fetch or mutate multiple resources of the same type across multiple collections. | reading-across-collections | 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. | custom-methods | handwritten | automatable | automatable |
| Custom resource fetch methods: fetch information for a single resource that cannot be expressed via a standard method. | custom-methods | handwritten | automatable | automatable |
| Custom Mutation Methods | ||||
| Backing up a resource: storing a copy of a resource at a particular point in time. | resource-revisions | unused or handwritten | automatable | automatable |
| Restoring a resource: setting a resource to a version from a particular point in time. | resource-revisions | unused or handwritten | automatable | automatable |
| Renaming a resource: modify the resource’s name or id while preserving configuration and data. | custom-methods | 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). | custom-methods | 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). | custom-methods | 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) | custom-methods | 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:
- Standard methods (on collections and resources)
- Standard batch or aggregate methods
- Custom methods (on collections, resources, or stateless)
- 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 an automated integration with exclusively resource-oriented clients such as Declarative clients, they are still a pattern that can be 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
- 2024-04-10: Imported from https://aip.dev/130.