REST API Naming Conventions: Best Practices and Guidelines

Naming your API properly is the first step in designing a good API. A well-structured API name follows a convention that makes it intuitive, readable, and maintainable. A meaningful API endpoint should follow some simple yet essential guidelines and rules.

In this article, you’ll learn the best practices for naming API endpoints and understand the difference between good and bad API routes. By following these conventions, you can create REST APIs that are clear, scalable, and easy to use.

---

Rule 01: Use Lowercase, Hyphens, and Full Words

Key Points:

• Always use lowercase in API endpoints.
• Use hyphens (-) instead of underscores (_) or spaces to separate words.
• Avoid abbreviations—use full, meaningful words instead.
• If an API accepts a variable, wrap it inside curly braces {} and use camelCase.

Examples

URI	Status	Why?
/products	✅ Good	Uses plural and lowercase.
/products/42/product-details	✅ Good	Uses lowercase and hyphen.
/orders/78/shipping-address/home	✅ Good	Uses lowercase and follows a hierarchy.
/employees/{employeeId}	✅ Good	Variable in camelCase.
/Products	❌ Bad	Uses title case.
/activeUsers	❌ Bad	Uses camelCase instead of hyphens.
/CategoryList	❌ Bad	Uses PascalCase.
/orders/78/shipping-addr	❌ Bad	Uses abbreviation.
/products/42/product_description	❌ Bad	Uses underscores.
/employees/{employee-id}	❌ Bad	Uses hyphen inside variable instead of camelCase.

---

Rule 02: Use a Forward Slash (/) to Indicate Hierarchy

The forward slash / should be used to indicate a hierarchical relationship between resources.

Example Hierarchies

E-commerce API

A store has products, and customers place orders. Each order has a shipping address.

URI	Status
/store/products/{productId}/reviews	✅ Good
/store/orders/{orderId}	✅ Good
/store/orders/{orderId}/shipping-address	✅ Good

Education API

A university has students enrolled in courses, and each course has an instructor.

URI	Status
/university/students/{studentId}/courses	✅ Good
/university/courses/{courseId}/instructor	✅ Good

---

Rule 03: Use Nouns, Not Verbs

RESTful APIs treat resources as nouns, not actions. The HTTP methods (GET, POST, PUT, DELETE) define the actions.

Examples

URI	Expects	Status	Why?
/books	Collection	✅ Good	Uses a noun, not a verb.
/users/{userId}/profile	Single user	✅ Good	Proper naming convention.
/book	Collection	❌ Bad	Uses singular for collection.
/fetchBook	Single resource	❌ Bad	Uses a verb.
/retrieveUser/{userId}	Single user	❌ Bad	Uses a verb.

---

Rule 04: Avoid Special Characters

Avoid using special characters (|, ^, @, #, !, etc.) in API endpoints. If your API needs to handle multiple values, use commas for separation.

Examples

URI	Status	Why?
/students/101,102,103/grades	✅ Good	Uses a comma for separation.
/students/101\|102\|103/grades	❌ Bad	Uses a special character |.
/products/32/price^discount	❌ Bad	Uses a special character ^.

---

Rule 05: Avoid File Extensions in URIs

APIs should not include file extensions like .json or .xml. Instead, clients should request different formats using a query parameter.

Examples

URI	Status	Why?
/music/songs/{songId}?format=json	✅ Good	Uses a query string.
/music/songs/{songId}?format=xml	✅ Good	Uses a query string.
/music/songs/{songId}.json	❌ Bad	Uses file extension.
/music/songs/{songId}.xml	❌ Bad	Uses file extension.

For static files like JavaScript and CSS, use clear endpoints and query strings instead of file extensions.

URI	Status	Why?
/assets/css/bootstrap/5.3/min	✅ Good	No file extension.
/assets/css/bootstrap/5.3/source	✅ Good	No file extension.
/assets/css/bootstrap/5.3/?format=min	✅ Good	Uses a query string.
/assets/css/bootstrap/5.3/?format=source	✅ Good	Uses a query string.
/styles/main.css	❌ Bad	Uses a file extension.

---

Rule 06: Use Query Parameters for Filtering

Use query parameters (?key=value) for filtering, pagination, and optional details instead of embedding them in the URI.

Examples

URI	Status	Why?
/events/{eventId}/attendees	✅ Good	Clear hierarchy.
/events/{eventId}/attendees?status=VIP	✅ Good	Uses a query parameter.
/posts?limit=5&page=3	✅ Good	Proper pagination.
/events/{eventId}/attendees/VIP	❌ Bad	Doesn’t use a query string.
/posts/page/3/limit/5	❌ Bad	Overcomplicates the URL.

---

Rule 07: No Trailing Slash

Avoid trailing slashes (/) at the end of API endpoints. They can lead to inconsistencies and unnecessary redirects.

Examples

URI	Status	Why?
/users/{userId}	✅ Good	No trailing slash.
/blog/{postId}/comments	✅ Good	No trailing slash.
/users/{userId}/	❌ Bad	Ends with a trailing slash.
/blog/{postId}/comments/	❌ Bad	Ends with a trailing slash.

---

Conclusion

Following these REST API naming conventions ensures that your API is consistent, readable, and easy to maintain. A well-structured API reduces confusion, improves usability, and enhances developer experience.