ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-314] Resource Identifier ​

Guidance ​

  • MUST have an identifier field for a resource.

  • SHOULD favor string type over number for identifiers.

    • Even if you choose a number as an identifier, tag it as a string in API documentation.

  • MAY use UUID or ULID for id generation.

    TIP

    💡 Sub-resources that are part of a parent resource and cannot exist independently may not have an id field. Instead, they would still have a unique field such as type or name.

  • SHOULD NOT use incrementing integers as id generation logic.

    TIP

    💡 Using incrementing integers can lead to potential security risks, such as easy predictability of IDs, which can be exploited to access unauthorized resources. Additionally, incrementing integers can cause issues with scalability and uniqueness across distributed systems.

    TIP

    💡 However, if the number of resources is guaranteed to be small, using UUIDs might be overkill. The API designer MAY opt for an incrementing number (converted to a string) if there are no security concerns.

  • SHOULD NOT use an external identifier as your resource identifier. The external identifier means it is not controlled by your system, such as an identifier generated by a third party system.

  • MUST use URL-friendly identifiers

    • To simplify encoding of resource IDs in URLs, they must match the regex [a-zA-Z0-9:._\-/]*. Resource IDs should only consist of ASCII strings using letters, numbers, underscore, minus, colon, period, and - on rare occasions - slash.

  • SHOULD consider using meaningful identifiers when appropriate, balancing between readability and security.

  • MUST ensure identifier uniqueness within the scope of the resource type.

  • SHOULD use consistent identifier formats across related resources.

Examples ​

Primary Resource JSON Representation ​

json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Primary Resource",
  "type": "primary",
  "subResource": {
    "type": "example",
    "name": "Sub Resource"
  }
}

URI Reference ​

  • Primary Resource:
http
GET /resources/123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
  • Sub-resource within the Primary Resource:
http
GET /resources/123e4567-e89b-12d3-a456-426614174000/sub-resource HTTP/1.1

Best Practices ​

  1. Consistency: Maintain consistent identifier formats across your API.
  2. Immutability: Once assigned, resource identifiers should not change.
  3. Opaqueness: Avoid encoding sensitive information in identifiers.
  4. Performance: Consider the impact of identifier choice on database indexing and query performance.
  5. Scalability: Choose identifier formats that can accommodate future growth.

References ​