Skip to main content
  • Status: Approved
  • Updated: 2026-11-21
Consistent identifier naming across Photon public HTTP APIs lets callers, generated SDKs, and agents predict field names and URL templates without memorizing per-endpoint conventions. This standard is part of Photon API Design Standards and uses the keywords MUST, MUST NOT, SHOULD, and MAY as described in RFC 2119.

Normative Rules

1. Primary identifier field (id)

Every resource object MUST use id as its own primary identifier field.
  • A resource object MUST NOT rename its own primary identifier to a resource-prefixed key such as projectId, apiKeyId, organizationId, or invoiceId.
  • Identifier fields MUST use lowercase id, never ID or Id.

2. Foreign-key identifier fields (<resource>Id)

References to other resources MUST be qualified in lowerCamelCase with the referenced resource name followed by the Id suffix (for example organizationId, projectId, or invoiceId).
  • Foreign-key references MUST NOT use bare id.
  • Foreign-key identifier fields MUST NOT use snake_case (such as project_id or api_key_id) or an uppercase ID suffix (such as projectID or organizationID).

3. URL path parameters ({<resource>Id})

Resource identifier path parameters in URL templates MUST use resource-qualified lowerCamelCase names ending in Id (for example /v1/projects/{projectId}/api-keys/{apiKeyId}).
  • URL path parameters MUST NOT use generic identifier names: {id}, {uuid}, {uid}, {guid}, or {pk} (case-insensitive).
  • All path parameters—including non-identifier parameters such as {slug} or {eventType}—MUST use lowerCamelCase and MUST NOT use snake_case ({project_id}), kebab-case ({project-id}), PascalCase ({ProjectId}), or an uppercase ID suffix ({projectID}).

4. Path parameter consistency

All routes sharing the same parent resource path prefix MUST use the exact same path parameter name.
  • An API MUST NOT mix different parameter names at the same path position across sibling or nested routes (for example /v1/projects/{projectId} alongside /v1/projects/{id}/api-keys, or /v1/organizations/{orgId} alongside /v1/organizations/{organizationId}).

5. Identifier format (advisory)

Resource identifiers SHOULD be opaque, immutable, type-prefixed strings (for example prj_01h455vb4pex5vsknk084sn02q, key_01h455vb4pex5vsknk084sn02r, or org_01h455vb4pex5vsknk084sn02s) so callers, SDKs, and logs can distinguish resource kinds without positional context. Callers SHOULD treat identifiers as opaque strings and MAY pass them directly into subsequent URL templates without parsing their internal structure.

Examples

Resource JSON objects

Good — primary key is id, foreign keys are qualified lowerCamelCase with Id:
Bad — resource-prefixed primary key (apiKeyId), snake_case, and uppercase ID:

Non-resource payloads

Non-resource payloads such as request bodies, aggregate summaries, and error responses are not required to define id, while still qualifying foreign keys in lowerCamelCase. Request body for POST /v1/projects:
Response body for GET /v1/projects/{projectId}/usage:

URL path templates and OpenAPI parameters

Good — resource-qualified lowerCamelCase path parameters, consistent across routes:
Bad — generic {id}, inconsistent parent parameter names, and non-camelCase casing:

Changelog

  • 2026-11-21: Approved and published as ADS-0001.

Feedback

Found a Photon API that does not follow this standard, or have a suggestion to improve it? Open an issue in photon-hq/api-design-standards (we do not accept external pull requests).