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. API 有时需要表示一种资源，其中该资源的一个实例始终存在于任何给定的父级中。 一个常见的用例是配置对象。

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. API 可以定义单例资源。 单例资源必须总是凭借其父级的存在而存在，每个父级只有一个。

For example:

message Config {
  option (google.api.resource) = {
    type: "api.googleapis.com/Config"
    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.name=users/*/config}"
    body: "config"
  };
}

• Singleton resources must not have a user-provided or system-generated ID; 单例资源不得具有用户提供或系统生成的 ID； their resource name includes the name of their parent followed by one static-segment. 他们的 resource name 包括他们的父母的名字，后跟一个静态段。
  • 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. 单例资源应该定义 Get 和 Update 方法，并且可以酌情定义自定义方法。
• Singleton resources are always singular.单例资源总是单一的。
  • Example: 'users/1234/thing'
• Singleton resources may parent other resources. 单例资源可能是其他资源的父级。

Changelog

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