ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-704] ID Field Convention ​

Guiding Principles ​

  • Unless there is a compelling reason to use a different format, UUID v4 SHOULD be used as the ID value.
    • If the resource is inherently count-based, such as /bugs/123, an incrementing number MAY be used.
  • It MUST be ensured that the ID value is unique within its resource type.
  • If the ID field may cause ambiguity, ${resourceType} MAY be added as a prefix to the field name.

Design Rationale ​

Every resource object must have an id field. When multiple resource objects are nested (as sub-resources), it may lead to ambiguity. Using the resource type as a prefix can enhance the clarity of identifying object types. This approach aligns with the principles of clarity and self-descriptiveness in API design.

Examples ​

DO:

json
{
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "orderId": "98765432-10ab-cdef-1234-567890abcdef"
}

DON'T:

json
{
  "id": "123",
  "order_id": 456
}

OpenAPI Specification ​

yaml
components:
  schemas:
    User:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: Unique identifier for the user
    Order:
      type: object
      properties:
        orderId:
          type: string
          format: uuid
          description: Unique identifier for the order

Implementation Considerations ​

  1. Ensure that your database schema and ORM (if used) can accommodate the prefixed ID fields.
  2. Consider implementing a utility function to generate and validate UUIDs in your codebase.
  3. When migrating existing systems to this convention, plan for backward compatibility and data migration strategies.

References ​