REST API URI naming rules - zamaniamin/python GitHub Wiki

REST API URI naming plays a crucial role in providing a clear and consistent representation of resources and operations. Here are some essential rules for naming REST API URIs:

1. Nouns for resources: URIs should use nouns to represent resources, rather than verbs. This aligns with the RESTful principle of treating resources as nouns and actions as verbs. For example, instead of /get-users, use /users for retrieving a list of users.

2. Plural for resources: Use plural nouns for resources, unless the resource is inherently singular. For instance, instead of /user/123, use /users/123 for accessing a specific user's details.

3. Hyphens for separation: Separate words in URIs using hyphens - rather than underscores _, which are typically reserved for file extensions. This makes URIs more readable and easier to understand for both humans and machines.

4. Lowercase for consistency: Keep all URI components in lowercase to maintain consistency and avoid ambiguity. This makes the API more predictable and easier to remember for developers.

5. Avoid special characters: Avoid using special characters like semicolons, question marks, parentheses, and brackets in URIs. These characters can cause issues with parsing and routing.

6. Path parameters for dynamic data: Use path parameters to represent dynamic data, such as user IDs or product IDs. This makes the API more flexible and easier to consume.

7. Clear and descriptive names: Choose clear and descriptive names for resources and operations to enhance understanding and usability. Avoid vague or ambiguous names that could lead to confusion.

8. Consistency with HTTP methods: Use consistent naming for resources and their corresponding HTTP methods. For instance, if you use /users for retrieving users, use /users for creating, updating, and deleting users as well.

9. Use consistent prefix for API endpoints: Consider using a consistent prefix for all API endpoints, such as /api/v1 or /api, to distinguish between different API versions or environments.

10. Document URI naming conventions: Clearly document your API's URI naming conventions in the API documentation to ensure consistency and clarity for developers.

By adhering to these REST API URI naming rules, you can create a consistent, readable, and easy-to-use API that aligns with RESTful principles and enhances developer experience.

Components of a URL:

Restful Endpoint: