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.


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: ""
    pattern: "users/{user}/config"

  string name = 1;

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}"
    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
  • Singleton resources must not define the Create, List, or Delete standard methods. The singleton is implicitly created or deleted when its parent is created or deleted.
  • Singleton resources should define the Get and Update methods, and may define custom methods as appropriate.
  • Singleton resources are always singular.
    • Example: 'users/1234/thing'
  • Singleton resources may parent other resources.


  • 2021-11-02: Added an example message and state parent eligibility.
  • 2021-01-14: Changed example from settings to config for clarity.