Rest Api Naming Convention

REST API naming conventions are essential for creating readable, understandable, and maintainable APIs. Following standard naming conventions helps ensure consistency and predictability, making it easier for developers to work with the API. Here are some best practices and examples for REST API naming conventions:

1. Use Nouns for Resource Names

Resource names should be nouns representing the entity being accessed or manipulated.

Examples:

• /users
• /orders
• /products

2. Use Plural Nouns

Even if you are dealing with a single resource, use the plural form to keep the API consistent.

Examples:

• /users instead of /user
• /orders instead of /order

3. Use HTTP Methods Appropriately

The HTTP method should indicate the action being performed.

• GET for retrieving resources
• POST for creating resources
• PUT for updating resources
• DELETE for deleting resources
• PATCH for partial updates

Examples:

• GET /users - Retrieve a list of users
• POST /users - Create a new user
• GET /users/{id} - Retrieve a specific user by ID
• PUT /users/{id} - Update a specific user by ID
• DELETE /users/{id} - Delete a specific user by ID
• PATCH /users/{id} - Partially update a specific user by ID

4. Use Path Variables for Resource Identification

Path variables should be used to identify specific resources.

Examples:

• /users/{userId}/orders/{orderId} - Retrieve a specific order for a specific user

5. Use Query Parameters for Filtering, Sorting, and Pagination

Query parameters can be used for additional operations such as filtering, sorting, and pagination.

Examples:

• GET /products?category=electronics - Retrieve products filtered by category
• GET /products?sort=price&order=asc - Retrieve products sorted by price in ascending order
• GET /products?page=2&limit=10 - Retrieve products with pagination (page 2, 10 items per page)

6. Use Hyphens for Readability

Hyphens improve readability in URIs. Avoid using underscores or camelCase.

Examples:

• /product-reviews instead of /productReviews or /product_reviews

7. Avoid Using Verbs in Endpoint Names

Resource URIs should be based on nouns, not actions.

Examples:

• Use /users instead of /getUsers or /createUser
• Use /orders instead of /placeOrder

8. Use Consistent Case for Resource Names

Resource names should follow a consistent case convention, typically kebab-case (hyphen-separated).

Examples:

• /user-profiles
• /order-items

9. Versioning the API

Include versioning in the API URL to ensure backward compatibility.

Examples:

• /v1/users
• /v2/orders

10. Status Codes

Use standard HTTP status codes to indicate the result of an operation.

Examples:

• 200 OK for successful GET requests
• 201 Created for successful POST requests
• 204 No Content for successful DELETE requests
• 400 Bad Request for invalid requests
• 404 Not Found for non-existing resources
• 500 Internal Server Error for server-side errors

Example REST API:

GET /v1/users?page=2&limit=10
POST /v1/users
GET /v1/users/{userId}
PUT /v1/users/{userId}
DELETE /v1/users/{userId}

GET /v1/users/{userId}/orders
POST /v1/users/{userId}/orders
GET /v1/users/{userId}/orders/{orderId}
PUT /v1/users/{userId}/orders/{orderId}
DELETE /v1/users/{userId}/orders/{orderId}

Following these conventions helps in designing REST APIs that are intuitive and easy to use for developers, leading to better integration and user experiences.