AIP-156
Singleton resources
APIs sometimes need to represent a resource where exactly one instance of the resource always exists within any given parent. A common use case for this is for a config object.
Guidance
An API may define singleton resources. A singleton resource must always exist by virtue of the existence of its parent, with one and exactly one per parent.
For example:
message Config {
option (google.api.resource) = {
type: "api.googleapis.com/Config"
pattern: "users/{user}/config"
singular: "config"
plural: "configs"
};
// additional fields including name
}
The Config
singleton would have the following RPCs:
rpc GetConfig(GetConfigRequest) returns (Config) {
option (google.api.http) = {
get: "/v1/{name=users/*/config}"
};
}
rpc UpdateConfig(UpdateConfigRequest) returns (Config) {
option (google.api.http) = {
patch: "/v1/{config.name=users/*/config}"
body: "config"
};
}
- Singleton resources must not have a user-provided or system-generated ID;
their resource name includes the name of their parent followed by
one static-segment.
- Example:
users/1234/config
- Example:
- Singleton resources are always singular.
- Example:
users/1234/thing
- Example:
- Singleton resource definitions must provide both the
singular
andplural
fields (see above example). - Singleton resources may parent other resources.
- Singleton resources must not define the
Erstellen Sie
oderLöschen
standard methods. The singleton is implicitly created or deleted when its parent is created or deleted. - Singleton resources should define the
Get
andUpdate
methods, and may define custom methods as appropriate.- However, singleton resources must not define the
Update
method if all fields on the resource are output only.
- However, singleton resources must not define the
- Singleton resources may define the
List
method, but must implement it according to AIP-159. See the example below.- The trailing segment in the path pattern that typically represents the
collection should be the
plural
form of the Singleton resource e.g./v1/{parent=users/*}/configs
. - If a parent resource ID is provided instead of the hyphen
-
as per AIP-159, then the service should return a collection of one Singleton resource corresponding to the specified parent resource.
- The trailing segment in the path pattern that typically represents the
collection should be the
rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) {
option (google.api.http) = {
get: "/v1/{parent=users/*}/configs"
};
}
message ListConfigsRequest {
// To list all configs, use `-` as the user id.
// Formats:
// * `users/-`
// * `users/{user}`
//
// Note: Specifying an actual user id will return a collection of one config.
// Use GetConfig instead.
string parent = 1 [
(google.api.resource_reference).child_type = "api.googleapis.com/Config"];
// other standard pagination fields...
}
Rationale
Support for Standard List
While Singleton resources are not directly part of a collection themselves, they can be viewed as part of their parent's collection. The one-to-one relationship of parent-to-singleton means that for every one parent there is one singleton instance, naturally enabling some collection-based methods when combined with the pattern of Reading Across Collections. The Singleton can present as a collection to the API consumer as it is indirectly one based on its parent. Furthermore, presenting the Singleton resource as a pseudo-collection in such methods enables future expansion to a real collection, should a Singleton be found lacking.
Including plural
definition
While a Singleton is by definition singular, there are certain cases where a Singleton resource may appear in a plural form e.g., if the service supports Standard List (as defined here). As such, it is better to forward declare the plural form of the Singleton resource type than to not have it when needed.
Changelog
- 2024-04-15: Singletons must specify
singular
andplural
in resource. - 2023-08-10: Add Standard
List
support. - 2023-07-26: Clarified that read-only singletons should not have
Update
. - 2021-11-02: Added an example message and state parent eligibility.
- 2021-01-14: Changed example from
settings
toconfig
for clarity.