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


2 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.