REST API URI Naming Conventions and Best Practices

Designing RESTful APIs is not just about functionality but clarity, consistency, and scalability. A well-structured API improves usability, maintenance, and developer experience.

This guide covers the best practices for REST API URI (Uniform Resource Identifier) naming, including:

✔ General URI Design Principles
✔ Best Practices for Resource Naming
✔ Common Mistakes to Avoid

🔹 What is a REST API URI?

A URI (Uniform Resource Identifier) uniquely identifies resources in a REST API.

📌 Example of a well-structured API endpoint:

GET /users/1

Here:

• /users represents a collection of user resources.
• /1 represents a specific user resource.

A good API URI should be descriptive, predictable, and easy to understand.

🔹 1️⃣ REST API URI Best Practices

1. Use Nouns, Not Verbs

A RESTful API should represent resources using nouns instead of actions (verbs).

✅ Good Example:

GET /products   → Retrieve all products
GET /products/10  → Retrieve product with ID 10
POST /products  → Create a new product

❌ Bad Example (Uses Verbs Instead of Nouns):

GET /getProducts
POST /createProduct
DELETE /removeProduct/10

📌 Why? REST is resource-based, and the HTTP methods (GET, POST, PUT, DELETE) already define actions.

2. Use Plural Nouns for Collections

When defining a collection of resources, use plural nouns to indicate multiple items.

✅ Good Example:

GET /users    → Get all users
GET /users/5  → Get user with ID 5

❌ Bad Example (Singular for Collections):

GET /user
GET /user/5

📌 Why? Plural naming clearly differentiates a collection vs. a single resource.

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

For operations like searching, filtering, sorting, and pagination, use query parameters, not custom URIs.

✅ Good Example:

GET /products?category=electronics
GET /products?sort=price&order=asc
GET /products?page=2&size=20

❌ Bad Example (Filters as Endpoints):

GET /products/electronics
GET /products/sortByPriceAscending
GET /products/page2/size20

📌 Why? Query parameters keep URIs clean, flexible, and extensible.

4. Use Hyphens (-) Instead of Underscores (_)

Use hyphens - in URIs instead of underscores _ for better readability.

✅ Good Example:

GET /product-categories

❌ Bad Example:

GET /product_categories

📌 Why? Hyphens improve URL readability in browsers and search engines.

5. Use Lowercase Letters in URIs

✅ Good Example:

GET /orders

❌ Bad Example:

GET /Orders
GET /ORDERS

📌 Why? Some servers are case-sensitive, and lowercase improves consistency.

6. Use Forward Slashes (/) for Hierarchy, Not Actions

Use forward slashes / to represent resource hierarchy, not actions.

✅ Good Example:

GET /users/10/orders/5  → Get order 5 of user 10

❌ Bad Example (Uses Actions in URI):

GET /getUserOrders?userId=10&orderId=5

📌 Why? A hierarchical structure makes URIs more organized and readable.

7. Use HTTP Methods Correctly

REST APIs rely on HTTP methods to perform actions.

Use HTTP Methods Correctly

❌ Bad Example (Including Action in URI Instead of Using HTTP Methods)

POST /users/create
GET /users/get/5
DELETE /users/delete/5

📌 Why? HTTP methods already specify the action, so the URI should represent the resource only.

8. Use Consistent Naming Conventions

APIs should follow a consistent pattern to improve usability.

✅ Good Example (Consistent and Logical Naming):

/users         → Get all users
/users/5       → Get user with ID 5
/users/5/orders → Get orders for user 5
/products      → Get all products
/products/10   → Get product with ID 10

❌ Bad Example (Inconsistent Naming):

/getAllUsers
/users/5/getOrders
/fetchProduct/10

📌 Why? Consistency improves usability for developers.

9. Use Meaningful Resource Names

URIs should describe what the resource represents, not the internal implementation.

✅ Good Example:

GET /customers/123/orders

❌ Bad Example (Includes Implementation Details):

GET /getOrdersForCustomer?id=123

📌 Why? Keep URIs descriptive, not procedural.

10. Keep URIs Short and Simple

✅ Good Example:

GET /products/25

❌ Bad Example (Too Long & Unnecessary Info):

GET /getProductDetailsForProductID25

📌 Why? Short URIs improve readability and ease of use.

🔹 Common REST API URI Mistakes to Avoid

❌ Using Verbs in URIs Instead of HTTP Methods

GET /fetchUsers  ❌
DELETE /removeUser/1  ❌

✅ Correct Approach

GET /users  ✅
DELETE /users/1  ✅

❌ Including File Extensions (.json, .xml) in URIs

GET /users.json  ❌

✅ Correct Approach

GET /users  ✅

❌ Using Mixed Naming Conventions

GET /UserProfile  ❌ (PascalCase)
GET /user_profile  ❌ (Underscores)

✅ Correct Approach

GET /user-profile  ✅ (Lowercase, hyphens)

🔹 Summary of REST API URI Best Practices

REST API URI Best Practices

🚀 Final Thoughts

A well-structured REST API improves usability, consistency, and scalability. By following these best practices, you can create APIs that are developer-friendly, easy to maintain, and scalable.

💡 Ready to build a great API? Start using clean, logical, and structured URIs in your next project! 🚀