REST API URL Examples

In this blog post, we will dive into some REST API URL design best practices using illustrative examples.

RESTful APIs (Representational State Transfer APIs) are web services that use HTTP methods to CRUD (Create, Read, Update, Delete) operations on resources. One of the key principles in designing a RESTful API is to have a well-structured and meaningful URL that represents the resources and actions upon them.

RESTful API URL Design Best Practices with Examples

1. Use Nouns to Represent Resources: 

Resources are typically nouns and should be expressed as plural. 

GET /users — Retrieves a list of users. 

GET /products — Retrieves a list of products. 

2. Use HTTP Methods for CRUD Operations: 

POST /users — Create a new user. 

GET /users/123 — Retrieve the user with ID 123. 

PUT /users/123 — Update user with ID 123. 

DELETE /users/123 — Delete the user with ID 123. 

3. Nest Resources to Represent Relationships: 

If a resource has a relationship with another resource, it can be nested. 

GET /users/123/orders — Retrieve all orders for user 123. 

GET /users/123/orders/456 — Retrieve order 456 of user 123. 

4. Keep URLs Simple: 

Avoid using verbs. Use nouns and leverage HTTP methods. 

✅ Do: DELETE /users/123 

❌ Avoid: GET /deleteUser/123 

5. Use Query Parameters for Filtering and Pagination: 

GET /users?status=active — Get active users. 

GET /products?category=electronics — Get products in the electronics category. 

GET /orders?page=2 — Get the second page of orders. 

6. Handle Associations: 

For many-to-many associations, create a new resource. 

GET /users/123/roles — Get roles associated with user 123. 

POST /users/123/roles — Assign a new role to user 123. 

7. Versioning: 

Versioning can help manage changes in APIs and ensure backward compatibility. 

GET /v1/users 

GET /v2/users 

8. Return Proper HTTP Status Codes: 

While not part of the URL, it’s crucial for the API to return the right HTTP status codes to represent the outcome of the operation. 

201 Created — Resource was successfully created. 

404 Not Found — Resource was not found. 

400 Bad Request — The client sent an invalid request.

Real-World REST API URL Examples

1. User Management:

List all users:

• Method: GET
• URL: /users

Retrieve a specific user:

• Method: GET
• URL: /users/{userId}

Create a new user:

• Method: POST
• URL: /users

Update a specific user:

• Method: PUT
• URL: /users/{userId}

Delete a specific user:

• Method: DELETE
• URL: /users/{userId}

2. Product Management:

List all products:

• Method: GET
• URL: /products

Retrieve a specific product:

• Method: GET
• URL: /products/{productId}

Add a new product:

• Method: POST
• URL: /products

Update a specific product:

• Method: PUT
• URL: /products/{productId}

Delete a specific product:

• Method: DELETE
• URL: /products/{productId}

3. Order Management for Users:

Retrieve all orders of a user:

• Method: GET
• URL: /users/{userId}/orders

Retrieve a specific order of a user:

• Method: GET
• URL: /users/{userId}/orders/{orderId}

4. Filtering, Sorting, and Pagination:

List active users:

• Method: GET
• URL: /users?status=active

List products in a specific category:

• Method: GET
• URL: /products?category=electronics

Retrieve the second page of users:

• Method: GET
• URL: /users?page=2

Retrieve users sorted by name:

• Method: GET
• URL: /users?sortBy=name

5. Versioning:

Retrieve users from version 1:

• Method: GET
• URL: /v1/users

Retrieve users from version 2:

• Method: GET
• URL: /v2/users

These are just some common examples to give you an idea. The design of a RESTful API URL will ultimately depend on the application's requirements and the resources it represents. The focus should be on clarity, simplicity, and adherence to standard conventions.

Keep refining and happy REST API designing!