AIP-2510

Project IDs

Historically, Google had two kinds of projects: API projects and App Engine projects. API projects used project numbers (e.g. 12345) as identifiers, and App Engine projects used project IDs (e.g. happy-armadillo-789) as identifiers. Later, Google converged API projects and App Engine projects, so now each project has both unique and immutable identifiers.

The two types of identifiers are used differently in different contexts, and create a lot of complexity for application development. One critical issue is that applications cannot reliably join data from different services, because different services use different project identifiers.

Guidance

TL;DR: The project number is the canonical identifier, and the project ID is an alias, and behaves as such. Additionally, third-party services are unable to accept project IDs.

The rationale for this is:

  • Each resource should always have one canonical identifier.
  • Because Google’s privacy policy restricts the use of project IDs, both internally and with partners, only the project number can be the canonical identifier.
  • Translating from an alias to a canonical identifier should be consistent everywhere, including referring to projects.
  • Returning resources with project numbers increases the chances that these are what users store, which may be important if using third-party services.

Google APIs

Externally-facing Google APIs should accept both project IDs and project numbers for incoming API requests.

However, the project number is the canonical identifier, and therefore APIs must use project numbers in responses, regardless of whether they were sent a project ID or a project number.

There are two exceptions to this rule:

  • Error responses must return the originally-provided value without modification. Error responses must not perform any translation between project IDs and project numbers.
  • If a service receives a resource name for a resource that the service does not own, it should not perform any translation between project IDs and project numbers for those resource names.

Internal Google services

Internal Google services must use project numbers for internal data storage and for output. Project identifiers are widely used as storage keys, which often appear in logs and metrics. Project IDs are user-settable and thus considered PII and user data, but project numbers are not.

Therefore, when an internal service calls an external Google APIs, it should use project numbers for making API requests.

Third-party services

Third-party services that are integrated with Google Cloud Platform must only store or provide project numbers. Google’s privacy policy prohibits sharing project IDs with third-party services, or providing a service for third-party services to translate between project IDs and project numbers at runtime.

Project identifier format

APIs must use project resource names as defined by the Resource Manager API to refer to projects, such as projects/123456. This allows the same API to work with other resources similar to projects, such as organizations and folders.

Changelog

  • 2019-08-11: Add an exception for resources that a service does not own.
  • 2019-06-19: Clarify how error messages should be treated
  • 2019-06-10: Minor language and organization tweaks