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.
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.
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.
- 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.
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.
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
- 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