AIP-215

API-specific protos

APIs are mostly defined in terms of protos which are API-specific, with occasional dependencies on common components. Keeping APIs isolated from each other avoids versioning problems and client library packaging problems.

Guidance

  • All protos specific to an API must be within a package with a major version (e.g., google.library.v1).
  • References to resources in other APIs must be expressed in terms of resource names (AIP-122), rather than using the resource messages.
  • When two versions of an API use effectively the same (API-specific) proto that proto must be duplicated in each version. (In other words, APIs must not create their own "API-specific common component" packages.)
  • Organization-specific common components may be placed in a common package, as described in AIP-213, but must not be used by any API outside that organization.
  • Global common components (also described in AIP-213) may be freely used by any API.

Rationale

When one API depends on protos defined by another API, this introduces uncertainty in terms of customer-expected behavior and client library dependency management. Suppose google.cloud.library.v1 depends on the protos (rather than abstract resources) in google.cloud.movies.v2. Any change to google.cloud.movies.v2 can cause problems.

For example:

  • If a field is added to a message in google.cloud.movies.v2, should customers using google.cloud.library.v1 expect to see it? If so, how soon after the field has been added? What about other API changes?
  • If the whole major version google.cloud.movies.v2 is deprecated (typically after v3 has been released), does that mean google.cloud.library.v1 has to change to use google.cloud.movies.v3, and if so, does that require a new major version for the library API as well?
  • How should client library versioning reflect changes to dependent APIs?

Keeping APIs isolated from each other, with a limited set of common components which are maintained in a highly disciplined way, reduces a lot of the issues with dependencies.

API-specific common components shared across versions add complexity for client library generation and packaging, and are inflexible in terms of versioning. When protos are duplicated because they start off the same in multiple versions, they can still diverge over time as they are isolated from each other.

Changelog

  • 2023-06-27: Restructured AIPs 215 and 213 for clarity.
  • 2023-05-11: Changed "PA" to "organization".
  • 2018-10-01: Initial AIP written.