REST API Naming Conventions: Best Practices and Examples

REST API naming conventions use nouns for resources in plural form and HTTP methods to define actions. Use lowercase letters with hyphens to separate words, and avoid verbs in URLs to keep them simple and consistent.

Syntax

REST API URLs represent resources using plural nouns and use HTTP methods to specify actions. Use lowercase letters and hyphens to separate words for readability.

• GET /books - Retrieve list of books
• POST /books - Create a new book
• GET /books/{id} - Retrieve a specific book
• PUT /books/{id} - Update a specific book
• DELETE /books/{id} - Delete a specific book

http

GET /resources
POST /resources
GET /resources/{id}
PUT /resources/{id}
DELETE /resources/{id}

Example

This example shows a REST API for managing users and their orders using proper naming conventions. It uses plural nouns, lowercase letters, and hyphens.

http

GET /users
POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users/123/orders
POST /users/123/orders
GET /users/123/orders/456
PUT /users/123/orders/456
DELETE /users/123/orders/456

Output

200 OK (for GET requests)
201 Created (for POST requests)
204 No Content (for DELETE requests)

Common Pitfalls

Common mistakes include using verbs in URLs, mixing singular and plural nouns, and inconsistent casing or separators.

• Wrong: GET /getUser (verb in URL)
• Right: GET /users (noun only)
• Wrong: GET /user/123 (singular noun)
• Right: GET /users/123 (plural noun)
• Wrong: GET /UserDetails (camelCase and uppercase)
• Right: GET /user-details (lowercase and hyphens)

http

Wrong:
GET /getUser
GET /user/123
GET /UserDetails

Right:
GET /users
GET /users/123
GET /user-details

Quick Reference

Rule	Example
Use plural nouns for resources	/books, /users
Use lowercase letters and hyphens	/user-profiles
Use HTTP methods for actions	GET, POST, PUT, DELETE
Avoid verbs in URLs	Use /orders not /getOrders
Use nested resources for hierarchy	/users/123/orders

Key Takeaways

Use plural nouns in lowercase with hyphens for resource names.

Use HTTP methods to define actions instead of verbs in URLs.

Keep URLs simple, consistent, and hierarchical for clarity.

Avoid mixing singular and plural forms in endpoints.

Use nested URLs to represent resource relationships.