How to Name REST API Endpoints: Best Practices and Examples

Name REST API endpoints using clear, plural nouns that represent resources, such as /users or /products. Use HTTP methods like GET, POST, PUT, and DELETE to define actions instead of verbs in the endpoint names.

Syntax

REST API endpoints should be named using plural nouns to represent resources. Use slashes / to separate resource levels. Avoid verbs in the endpoint path; instead, use HTTP methods to indicate actions.

• Resource: The main noun representing the data, e.g., users, orders.
• Sub-resource: Nested resources, e.g., users/123/orders.
• Query parameters: For filtering or searching, e.g., users?active=true.

plaintext

/resources
/resources/{id}
/resources/{id}/subresources
/resources?filter=value

Example

This example shows how to name endpoints for a simple user management API. The endpoints use plural nouns and HTTP methods to perform actions.

plaintext

GET /users          # List all users
GET /users/123      # Get user with ID 123
POST /users         # Create a new user
PUT /users/123      # Update user with ID 123
DELETE /users/123   # Delete user with ID 123

Common Pitfalls

Common mistakes when naming REST API endpoints include:

• Using verbs in endpoint names like /getUser or /createUser instead of HTTP methods.
• Using singular nouns inconsistently, which can confuse users.
• Mixing resource names and actions in the path.

Correct naming keeps endpoints simple and intuitive.

plaintext

Wrong:
GET /getUser/123
POST /createUser

Right:
GET /users/123
POST /users

Quick Reference

Rule	Example
Use plural nouns for resources	/users, /products
Use HTTP methods for actions	GET, POST, PUT, DELETE
Use nested resources for hierarchy	/users/123/orders
Use query parameters for filtering	/users?active=true
Avoid verbs in endpoint paths	Not /getUser, use GET /users

Key Takeaways

Use plural nouns to name REST API endpoints representing resources.

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

Keep endpoint paths simple, consistent, and hierarchical.

Use query parameters for filtering and searching resources.

Avoid mixing actions and resource names in endpoint paths.