- Status: Approved
- Updated: 2026-11-21
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, orinvoiceId. - Identifier fields MUST use lowercase
id, neverIDorId.
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 asproject_idorapi_key_id) or an uppercaseIDsuffix (such asprojectIDororganizationID).
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 uselowerCamelCaseand MUST NOT usesnake_case({project_id}),kebab-case({project-id}),PascalCase({ProjectId}), or an uppercaseIDsuffix ({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 exampleprj_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 isid, foreign keys are qualified lowerCamelCase with Id:
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 defineid, while still qualifying foreign keys in lowerCamelCase.
Request body for POST /v1/projects:
GET /v1/projects/{projectId}/usage:
URL path templates and OpenAPI parameters
Good — resource-qualifiedlowerCamelCase path parameters, consistent across routes:
{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 inphoton-hq/api-design-standards (we do not accept external pull requests).