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"
};
// 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 resources may parent other resources.
- Singleton resources must not define the
Create
orDelete
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.
Changelog
- 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.