[ADP-309] URI format convention

reviewing phase 1

repeat 306

Guidance

• MUST use kebab-case for resource names and modifiers in URIs
• SHOULD use lowercase letters for all parts of the URI
• MUST use hyphens (-) to separate words in multi-word resource names or modifiers
• SHOULD keep URIs as short and descriptive as possible
• MUST NOT include file extensions in URIs (e.g., .json, .xml)
• SHOULD use plural nouns for collection resources
• MAY use singular nouns for singleton resources or specific instances
• SHOULD use nouns rather than verbs to represent resources

Design Thinking

This rule pertains to the naming of resource collections and the modifiers/decorators used to describe the collections. Consistent URI formatting improves API readability, predictability, and overall developer experience.

TIP

💡 When there's a need to put the path in a property, you'll need to transfer it to camelCase since we defined that properties in JSON should be camelCase.

Examples

Good examples:

https://api.example.com/api-principles
https://api.example.com/api-principles/recently-visited
https://api.example.com/users
https://api.example.com/users/123/profile-pictures

Bad examples:

https://api.example.com/APIprinciples
https://api.example.com/api_principles/recentlyVisited
https://api.example.com/user
https://api.example.com/users/123/profilePictures.jpg

Implementation Details

1. Resource naming:

   • Use plural nouns for collections: /users, /products, /orders
   • Use singular nouns for singletons or specific instances: /user/profile, /product/featured

2. Query parameters:

   • Use camelCase for query parameter names: /users?sortBy=lastName&filterBy=active

3. Versioning:

   • If API versioning is required, include it at the beginning of the path: /v1/users, /v2/products

4. Nested resources:

   • Use logical nesting to represent relationships: /users/123/orders/456

5. Actions:

   • For actions that don't fit the standard CRUD operations, use a noun that represents the action result: /users/123/password-reset instead of /users/123/reset-password

   About API Design for Password Reset

   When designing APIs related to authorization and authentication, there are always some controversies, believing that these APIs do not quite conform to the "RESTful" spirit. This controversy is not uncommon on the internet, with some people advocating for abstracting login behavior into a session and then designing the session as a resource; others believe that login-related operations should be designed in an RPC style.

   This specification believes that with OAuth2.0 and OIDC, there are already mature solutions. Therefore, it is possible to directly reference how identity providers (IDPs) that have implemented OAuth2.0/OIDC are designed, taking password reset as an example, the following methods are more in line with the thinking of this specification:

   DELETE /..../password
   
   (https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_user_password_delete.htm)
   
   POST /.../password-reset
   
   (https://auth0.com/docs/authenticate/database-connections/password-change)
   
   PATCH /.../user with { password }
   
   (https://auth0.com/docs/authenticate/database-connections/password-change#directly-set-the-new-password)

   These methods can serve as a reference for designing APIs related to authentication and authorization.

Related ADPs

• ADP-24: Versioning mechanism
• ADP-301: Resource-oriented design

References

• https://api.otto.de/portal/guidelines/r000023
• Google API Design Guide - Resource Names
• Microsoft REST API Guidelines - URI Components

Changelog

• 2024.09.24 Add password-reset api design thinking