When designing RESTful APIs, one of the most common debates among developers is whether to use singular or plural nouns for resource endpoints. Both approaches have their merits:
// Singular convention
GET /user/123
POST /user
PUT /user/123
// Plural convention
GET /users/123
POST /users
PUT /users/123
Looking at major APIs reveals a preference for plural nouns:
- GitHub API:
/users/{username}
,/repos/{owner}/{repo}
- Twitter API:
/users/{id}
,/tweets/{id}
- Stripe API:
/customers/{id}
,/charges/{id}
The plural form often makes more sense logically:
// With plural nouns, collection operations feel more natural
GET /users // Get all users
POST /users // Create a new user
GET /users/{id} // Get specific user
Singular forms can create confusion when dealing with collections:
// This feels inconsistent
GET /user // Gets all users? Or performs some user action?
POST /user // Creates a user
GET /user/{id} // Gets specific user
Here's how you might implement a REST API using the plural convention in Node.js/Express:
const express = require('express');
const app = express();
// Users collection
app.get('/users', (req, res) => {
// Return list of all users
});
app.post('/users', (req, res) => {
// Create new user
});
// Individual user
app.get('/users/:id', (req, res) => {
// Return specific user
});
app.put('/users/:id', (req, res) => {
// Update specific user
});
app.delete('/users/:id', (req, res) => {
// Delete specific user
});
There are exceptions where singular might make more sense:
- Singleton resources (e.g.,
/account
when a user only has one account) - Actions that don't represent CRUD operations (e.g.,
/user/login
) - When dealing with uncountable nouns (e.g.,
/equipment
rather than/equipments
)
Based on industry practice and logical consistency:
- Default to plural nouns for collections (
/users
,/products
) - Use singular for singleton resources (
/profile
,/settings
) - Be consistent throughout your entire API
- Document your naming convention for developers
When designing RESTful APIs or website URL structures, one persistent question emerges: should resource identifiers use singular or plural nouns? This decision affects both API consumers and search engine optimization.
Examining major platforms reveals mixed approaches:
- Plural advocates: Twitter (/users/), GitHub (/repositories/), StackOverflow (/questions/)
- Singular proponents: WordPress (/post/), some eCommerce platforms (/product/)
// Plural convention example
GET /api/v1/users/123
POST /api/v1/users
// Singular convention example
GET /api/v1/user/123
POST /api/v1/user
Plural naming often makes more sense technically:
- Collections naturally represent multiple resources (/users)
- Individual resources exist within collections (/users/123)
- Maintains consistency with database tables (users table)
Here's how this might look in different frameworks:
Express.js (Node.js)
// Plural route definition
app.get('/users', (req, res) => {
// Return user collection
});
app.get('/users/:id', (req, res) => {
// Return specific user
});
Django (Python)
# urls.py
from django.urls import path
from . import views
urlpatterns = [
path('users/', views.UserList.as_view()),
path('users/<int:pk>/', views.UserDetail.as_view()),
]
From an SEO perspective:
- Plural forms often match natural search queries ("find users" vs "find user")
- Google treats singular/plural similarly but plural may capture more long-tail traffic
- Consistency across your site matters more than the specific choice
After evaluating these factors, I recommend:
- Use plural nouns for collections (/users)
- Maintain consistency across your entire API/website
- Document your convention in API guidelines
- Consider your specific domain (e.g., /equipment might stay singular)
The most important factor is consistency - choose one approach and stick with it throughout your project.