ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-306] URI Design Patterns ​

Overview ​

Designing paths for APIs is a task that does not have a completely correct answer and is prone to design disagreements. This specification attempts to provide some observed design patterns, which may improve over time. We encourage developers to share effective URI design examples they encounter (see ADP-307) to help refine these guidelines.

Guidance ​

  • SHOULD use lowercase letters for URI paths.

  • SHOULD use hyphens (-) to separate words in URI paths (i.e., use kebab-case).

  • MUST use forward slashes (/) to indicate hierarchy.

  • SHOULD shorten URIs as much as possible while maintaining clarity.

  • MUST NOT include file extensions (e.g., .json, .xml) in URIs.

  • SHOULD use query parameters for filtering, sorting, and pagination.

    INFO

    This means that paths should not (SHOULD NOT) be used for these three tasks. For the three major collection operations, see ADP-311, ADP-312, ADP-313.

  • MUST encode special characters in URIs according to RFC 3986.

  • MUST NOT end URIs with a trailing slash (/).

    INFO

    Since the last character in a URI path does not add semantic value and may cause confusion, URIs must not end with a trailing slash (/).

    Correct practice

    raw
    /customers/{user-id}/addresses/{address-id}

    Incorrect practice

    raw
    /customers/{user-id}/addresses/{address-id}/

  • SHOULD refer to the path patterns mentioned below for design.

  • If needed, MAY include API version in the URI (e.g., /v1/users). See ADP-41: API Versioning.

Path Design Patterns ​

Pattern 1: Based on Collections ​

Basic URI for Collections:

http
/{resources}

Example:

http
GET /users HTTP/1.1

Pattern 1.1: Specific Resource in a Collection ​

URI to access a specific resource in a collection:

http
/{resources}/{resource-id}

Example:

http
GET /users/12345 HTTP/1.1

Pattern 1.1B: Specific Resource in a Collection without ID Field ​

In some cases, it is necessary to access resources without a traditional id identifier. In this case, we must determine a unique field, such as name or type, to include in the URI as a reference.

URI to access a resource without ID:

http
/{resources}/{resource-type|resource-name}

Example:

http
GET /apis/{api-id}/stages/dev HTTP/1.1

This example demonstrates accessing a specific stage (dev) of the API identified by {api-id}, where the stage does not have a traditional id but can be uniquely identified by its name.

Guidelines for Resources without ID ​

  1. Unique Field Identification: Ensure the selected field (e.g., name or type) is unique in the context used.
  2. Consistency: Consistently use the same unique field across similar types of resources to avoid confusion.
  3. Clarity: The selected field should clearly convey what resource it represents, making the URI easy to understand.

Pattern 1.2: Nested Resources ​

URI to access nested resources:

http
/{resources}/{resource-id}/{nested-resources}/{nested-resource-id}

Example:

http
GET /users/12345/orders/67890 HTTP/1.1

Pattern 2: Based on Actions ​

In RESTful API design, HTTP POST typically represents CREATE. However, many actions do not fully conform to standard CRUD operations. To address this, action verbs can be used to indicate actions while maintaining the principle that URIs should not contain verbs. These URIs should always use POST as the HTTP method.

Example Action URIs:

http
POST /search
POST /users/login
POST /documents/12345/publish

TIP

HTTP methods should not (SHOULD NOT) be placed in the path, such as POST /documents/delete.

Pattern 3: Resources with Modifiers ​

Modifiers can be used to filter or sort collections. This pattern should be intuitive and self-explanatory.

Basic URI with Modifiers:

http
/{resources}/{modifier}

Example:

http
GET /songs/recently-played HTTP/1.1
GET /articles/top-rated HTTP/1.1

References ​