Singular vs Plural in RESTful URL Design: Best Practices for API Endpoint Naming


21 views

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:

  1. Default to plural nouns for collections (/users, /products)
  2. Use singular for singleton resources (/profile, /settings)
  3. Be consistent throughout your entire API
  4. 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:

  1. Collections naturally represent multiple resources (/users)
  2. Individual resources exist within collections (/users/123)
  3. 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:

  1. Use plural nouns for collections (/users)
  2. Maintain consistency across your entire API/website
  3. Document your convention in API guidelines
  4. 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.