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.
- All protos specific to an API must be within a package with a major version
- 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.
When one API depends on protos defined by another API, this introduces uncertainty
in terms of customer-expected behavior and client library dependency management.
google.cloud.library.v1 depends on the protos (rather than abstract resources)
google.cloud.movies.v2. Any change to
google.cloud.movies.v2 can cause problems.
- If a field is added to a message in
google.cloud.movies.v2, should customers using
google.cloud.library.v1expect 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.v2is deprecated (typically after v3 has been released), does that mean
google.cloud.library.v1has 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.
- 2023-06-27: Restructured AIPs 215 and 213 for clarity.
- 2023-05-11: Changed "PA" to "organization".
- 2018-10-01: Initial AIP written.