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; however, unlike normal aliases, it should be returned if it is what the user sent. Additionally, third-party services are unable to accept project IDs.
The rationale for this is:
- Each resource should always have one canonical identifier.
- However, even though the project number is the canonical identifier, a policy of returning it even if the user sent a project ID has proven to be unfriendly to both humans and declarative tools.
Externally-facing Google APIs should accept both project IDs and project numbers for incoming API requests.
However, even though the project number is the canonical identifier as described in AIP-122, services should return whichever ID the user sent. The reason for this is because automatic translation between user-friendly project IDs and user-unfriendly project numbers has proven to cause real-world difficulty for users, and also for declarative tools (see AIP-128 for more on declarative-friendliness).
Two additional points:
- 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
Services 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.
- 2021-07-29: Reversed previous guidance on returning project IDs; this AIP now advocates returning what the user sent.
- 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