AIP-213

Common components

As specified in AIP-215, APIs must be self-contained except for the use of "common component" packages which are intended for use by multiple APIs.

There are two kinds of common component packages:

  • Organization-specific common components, covering organization-specific concepts such as a "viewport" in Maps.
  • Global common components which are generic (i.e. not domain-specific), such as "timestamp" or "postal address".

Where it is safe to share a single representation across multiple APIs, common components can make it easier for clients to interact with those APIs. Concept-specific client code can be written once, and messages can be used from the response of one API in the request of another without clunky copying, for example.

This benefit comes with significant restrictions and limitations, however, and should not be attempted lightly.

Note that even if the domain of a component is common, the requirements of a component may be organization-specific. For example, some organizations may have particular requirements of how financial values are represented, leading to multiple finance-oriented organization-specific common components - because any global common component would either not meet the organization-specific requirements, or be too complex for general use.

Guidance

  • Organization-wide common component packages must end with .type, e.g. google.geo.type or google.shopping.type.
  • Organizations must consult the API design team before creating a new organization-wide common component package.
  • Organization-wide common component packages must be published in the googleapis repository.
  • Organizations creating and publishing a new organization-wide common component package must update this AIP to include it in the list below.
  • Organizations must not define generic components in organization-specific common component packages, instead preferring global common components.
  • Common components must not be "moved" (that is, deleted from one common component package and added to a different one) from an organization-specific common component package to a global common component package or vice versa.
    • A common component may be copied from an organization-specific common component package to a global common component package (without deleting the original component) if it is found to be more widely-applicable than originally expected.
  • Fields should not be added to existing messages.
  • Values should not be added to existing enums.
  • Fields must not be removed from existing messages.
  • Values must not be removed from existing enums.
  • While documentation may be clarified, it should not change the meanings of existing values, including the validity of any given message or set of messages.
  • New proto messages and enums may be added to common component packages.
    • API teams should allow sufficient time for propagation to clients before using the new messages and enums in their APIs. Fields may take some time for any changes to propagate through publication to client libraries and other surfaces.
    • API teams should consult widely within their organization, and ideally with the API design team, before adding a new message or enum, due to the limitations listed above.

Existing global common components

The global common components, which public-facing protos for an API may safely import, are as follows:

Note that some common components may have internal-only fields. APIs should generally only rely on fields which have been released into open source.

Google APIs may also import google.iam.v1.*, which provides the IAM messages used throughout Google.

Note: Many APIs also import components from other packages for internal-only use (e.g. to apply visibility labels or provide instructions to internal infrastructure). This is acceptable provided that the public components do not contain such references.

Protobuf types

The google.protobuf package is somewhat special in that it is shipped with protocol buffers itself, rather than with API tooling. (For most API designers, this should be an implementation detail).

This package includes a small library of types useful for representing common programming language constructs:

  • google.protobuf.Duration: Durations, with nanosecond-level precision. The protobuf runtime provides helper functions to convert to and from language-native duration objects where applicable (such as Python's timedelta).
  • google.protobuf.Struct: JSON-like structures (a dictionary of primitives, lists, and other dictionaries). The protobuf runtime provides helper functions in most languages to convert struct objects to and from JSON.
  • google.protobuf.Timestamp: Timestamps, with nanosecond-level precision. The protobuf runtime provides helper functions in most languages to convert to and from language-native timestamp objects (such as Python's datetime).

API Types

The google.type package provides a "standard library" of types useful for representing common concepts in APIs. While types are added from time to time and the definitive list is always the code, several types deserve note:

Adding to common protos

Occasionally, it may be useful to add protos to these packages or to add to the list of commonly-available protos. In order to do this, open an issue on the AIP repository in GitHub, noting the guidelines above.

Existing organization-specific common component packages

The following organization-specific common component packages exist and conform with the above guidance:

Non-conformant common component packages

The following common component packages exist, but do not conform with the above guidance, and do not form a precedent for further such packages.

Rationale

Common components are effectively unversioned: APIs evolve independently of each other, both in terms of definition and implementation. A change such as adding a field is backward-compatible and predictable in specific APIs, and the API team can ensure that the server implementation is available before the API definition is published. By contrast, a change in a common component would effectively be universally available even if most API implementations did not take it into account.

Adding a new message or enum is backward-compatible, as it does not affect existing APIs that may import other messages or enums from the same common component package.

Consultation with the API design team is required for global common components and suggested for organization-specific common components as the border between "generic" and "organization-specific" is a gray area; some generic concepts have organization-specific use cases which surface through the components.

Changelog

  • 2023-06-27: Restructured AIPs 215 and 213 for clarity, and introduced the concept of organization-wide common protos more formally.
  • 2018-08-17: Initial AIP written.