DEV Community

Preecha
Preecha

Posted on

Should REST API Resource Names Be Plural or Singular?

TL;DR

Use plural names for REST API resource collections: /pets and /pets/{id}, not /pet and /pet/{id}. Plural names make collection semantics explicit, align with HTTP methods, and give developers a consistent mental model. Modern PetstoreAPI uses plural resource names throughout its API design.

Try Apidog today

Introduction

When designing an endpoint to retrieve a user by ID, should you use /user/123 or [REDACTED PATH]?

Both can work technically, but `[REDACTED PATH] a collection and one of its members.

The old Swagger Petstore used /pet/{id}, which helped popularize the singular pattern. Modern PetstoreAPI uses plural names consistently across its endpoints.

If you’re building or testing REST APIs, Apidog helps you validate resource naming conventions, test endpoint consistency, and check your API against REST best practices. You can import OpenAPI specifications and identify naming inconsistencies before they reach production.

In this guide, you’ll learn:

  • Why REST collections are typically plural
  • How HTTP methods map to collection and item endpoints
  • How to design nested resources
  • When singular names are appropriate
  • How to test naming conventions with Apidog

The Plural vs. Singular Debate

The debate usually comes down to what the URL represents.

The Singular Argument

“/user/123 returns one user, so the path should be singular.”

This argument focuses on the response body. Since the server returns one object, a singular noun appears natural.

The Plural Argument

“/users is the collection, and `[REDACTED PATH]

This argument focuses on the resource structure. The collection path stays the same whether you list the collection or address one member.

Why the Choice Matters

Resource naming affects more than URL style:

  • Consistency: Mixed conventions make an API harder to learn.
  • Mental models: Developers can predict how collection and item URLs relate.
  • Code generation: Client tools often derive method and model names from paths.
  • Documentation: A consistent structure requires fewer special explanations.

Why Plural Resource Names Work Well

1. Collections Are Plural

In a REST API, a collection contains multiple resources:

GET /users
GET [REDACTED PATH]
POST /users
DELETE /users/123
Enter fullscreen mode Exit fullscreen mode

These operations have a consistent interpretation:

  • GET /users retrieves the users collection.
  • `GET [REDACTED PATH]
  • POST /users adds a new member to the collection.
  • `DELETE [REDACTED PATH]

With a singular collection path, the meaning is less clear:

GET /user       # Which user or set of users?
GET /user/123   # One user
POST /user      # Add to what collection?
Enter fullscreen mode Exit fullscreen mode

2. HTTP Methods Map Naturally to Collections

Plural paths make the relationship between HTTP methods and resources explicit:

Method Endpoint Operation
GET /users List users
POST /users Create a user
GET /users/123 Retrieve user 123
PUT `[REDACTED PATH]
DELETE `[REDACTED PATH]

The collection is /users; an individual item is addressed by adding its identifier.

3. Plural Names Keep Endpoints Consistent

A predictable API uses the same pattern for every resource:

GET /pets
GET /pets/123

GET /orders
GET /orders/456
Enter fullscreen mode Exit fullscreen mode

With singular names, the collection and item structure often becomes inconsistent:

GET /pet       # Collection path is unclear
GET /pet/123   # Item path
GET /pets      # A second collection convention
Enter fullscreen mode Exit fullscreen mode

4. Common APIs Use Plural Names

Many widely used APIs use plural collection names, including:

  • GitHub: /repos, /users, /issues
  • Stripe: /customers, /charges, /subscriptions
  • Twilio: /accounts, /messages, /calls
  • Google APIs: /users, /groups, /files

Modern PetstoreAPI follows the same pattern with /pets, /orders, and /users.

Use a Collection Mental Model

A collection is a set of related resources. In a pet store API:

  • /pets represents all pets.
  • /orders represents all orders.
  • /users represents all users.

A typical collection supports these operations:

GET    /pets           # List pets
POST   /pets           # Create a pet
GET    /pets/{id}      # Retrieve one pet
PUT    /pets/{id}      # Replace one pet
DELETE /pets/{id}      # Delete one pet
Enter fullscreen mode Exit fullscreen mode

Query parameters can refine collection requests without changing the resource name:

GET /pets?status=AVAILABLE
Enter fullscreen mode Exit fullscreen mode

Design Nested Resources Consistently

Nested collections should also use plural names:

GET  /pets/{id}/photos
POST /pets/{id}/photos
GET  /pets/{id}/photos/{photoId}
Enter fullscreen mode Exit fullscreen mode

Here:

  • /pets is the top-level collection.
  • {id} identifies one pet.
  • /photos is the collection of photos belonging to that pet.
  • {photoId} identifies one photo.

The same structure applies to orders:

GET /orders/{orderId}/items
Enter fullscreen mode Exit fullscreen mode

Modern PetstoreAPI Example

Modern PetstoreAPI uses this collection-and-item structure:

GET  /pets
GET  /pets/{petId}
GET  /pets/{petId}/photos
POST /pets/{petId}/vaccinations

GET  /orders
GET  /orders/{orderId}
GET  /orders/{orderId}/items
Enter fullscreen mode Exit fullscreen mode

Each collection is plural, and each individual resource is selected by an identifier within that collection.

Modern PetstoreAPI Endpoint Examples

Pet Resources 

GET    /pets
POST   /pets
GET    /pets/{petId}
PUT    /pets/{petId}
DELETE /pets/{petId}
GET    /pets?status=AVAILABLE
Enter fullscreen mode Exit fullscreen mode

Order Resources 

GET    /orders
POST   /orders
GET    /orders/{orderId}
PUT    /orders/{orderId}
DELETE /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

User Resources 

GET    /users
POST   /users
GET    [REDACTED PATH]
PUT    /users/{userId}
DELETE [REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Nested Resources 

GET  /pets/{petId}/photos
POST /pets/{petId}/photos

GET  /pets/{petId}/vaccinations
POST /pets/{petId}/vaccinations

GET  /orders/{orderId}/items
Enter fullscreen mode Exit fullscreen mode

Check the full REST API documentation for complete endpoint listings.

Common Arguments for Singular Names

“The Response Is Singular”

Claim: GET /user/123 returns one user, so singular naming is more accurate.

Counter: The URL identifies the resource location, not the number of objects in the response. `[REDACTED PATH] response contains one item.

“It Reads Better in Code”

Claim: getUser(id) reads better than getUsers(id).

Counter: Client method names do not have to match URL segments:

js
// URL: GET [REDACTED PATH]
function getUser(id) {
return api.get([REDACTED PATH]
}
`

The method describes the returned item, while the URL describes the resource hierarchy.

“Singular Avoids Grammar Problems”

Claim: Some resource names, such as status or information, do not have obvious plurals.

Counter: These may be singleton resources or uncountable nouns. Singular names are appropriate when the resource is not a collection:

http
GET /status
GET /configuration
GET /users

“My ORM Uses Singular Table Names”

Claim: Database tables are named user and order, so the API should use the same names.

Counter: API paths and database schemas serve different purposes. Avoid exposing database implementation details in your public API. The API can use /users and /orders even if the underlying tables are singular.

Test Resource Naming with Apidog

Use automated checks to catch inconsistent resource paths in an OpenAPI project or request collection.

Import the Modern PetstoreAPI Specification

  1. Import the Modern PetstoreAPI OpenAPI specification into Apidog.
  2. Review the generated endpoint list.
  3. Check that collection paths use plural names.
  4. Look for singular/plural inconsistencies in nested paths.
  5. Add tests for paths that should remain stable over time.

Create a Naming Convention Test

The following test checks whether the first path segment ends in s:

`js
pm.test("Resource names are plural", function () {
const path = pm.request.url.getPath();
const segments = path.split("/").filter(Boolean);

const resource = segments[0];
pm.expect(resource).to.match(/s$/);
});
`

This simple check works for common resources such as /pets, /orders, and /users. Extend the rule for known exceptions such as singleton resources, actions, or naturally plural nouns.

Validate Consistency

Review your API for:

Apidog can validate the responses and help you check naming consistency across the API.

Edge Cases and Exceptions

Plural collection names are a useful default, not an absolute requirement.

Singleton Resources

Use singular names for resources that exist only once:

`http
GET /status
GET /configuration
GET /health
GET /metrics
`

These endpoints represent one system-level resource rather than a collection of items.

Controller or Action Resources

Some operations do not map cleanly to CRUD:

`http
POST /login
POST /logout
POST /search
`

These are acceptable exceptions when the path represents an action rather than a resource collection.

Uncountable Nouns

Some nouns do not have a useful plural form:

`http
GET /information
GET /data
GET /equipment
`

Use the form that best communicates the resource. These cases are less common in typical CRUD APIs.

Modern PetstoreAPI Approach

Modern PetstoreAPI separates the common cases:

`http

Collections

GET /pets
GET /orders
GET /users

Singletons

GET /health
GET /metrics

Actions

POST /login
POST /logout
`

Conclusion

Plural REST resource names make collection semantics visible and keep HTTP operations predictable. Use plural names for collections, then address individual items by identifier:

`http
GET /pets
GET /pets/123
`

Key takeaways:

  • Use plural names for collections such as /pets, /orders, and /users.
  • Access individual items within those collections, such as /pets/123.
  • Use singular names for singleton resources such as /status and /health.
  • Use action-style paths only when the endpoint represents an operation rather than a resource.
  • Keep naming consistent across top-level and nested resources.
  • Test naming conventions with Apidog.

For a new API, choose plural collection names and document the convention in your API guidelines. For an existing production API, prioritize client compatibility over a naming change.

Next Steps

  1. Review your API endpoints for singular/plural inconsistencies.
  2. Compare your structure with Modern PetstoreAPI examples.
  3. Add naming checks to your Apidog test suite.
  4. Update your OpenAPI specification with consistent plural resource names.

FAQ

Should I change my existing API from singular to plural?

Changing resource paths in a production API is a breaking change. Consider:

  • Adding plural paths in a new API version
  • Maintaining backward compatibility for existing clients
  • Documenting the naming convention clearly
  • Migrating clients gradually

Do not break existing clients solely to improve naming consistency.

What about resources that are already plural?

Keep naturally plural names as they are:

`http
GET /analytics
GET /series
GET /species
`

These words are already plural or have the same singular and plural form.

How should I handle nested resources?

Use plural names for both collection levels:

`http
GET [REDACTED PATH]
GET /pets/{petId}/vaccinations
GET /orders/{orderId}/items
`

The parent identifier selects one parent resource; the final plural segment identifies its child collection.

What if my team prefers singular names?

Consistency within an existing API matters most. If your team has standardized on singular names and changing them would create compatibility problems, keep the current convention and document it.

For a new API, plural collection names are generally easier for developers to understand.

Does GraphQL use plural or singular names?

GraphQL fields usually communicate whether they return one item or a list:

`graphql
query {
user(id: "123") {
id
}

users(limit: 10) {
id
}
}
`

This differs from REST because GraphQL queries explicitly describe the requested field and response shape.

How does Modern PetstoreAPI handle resource naming?

Modern PetstoreAPI uses plural names consistently across its REST endpoints. Refer to the REST API guide for complete examples.

Can I test naming conventions automatically?

Yes. Import your OpenAPI specification into Apidog and create automated tests that check collection paths, nested resources, and documented exceptions.

What about non-English APIs?

Apply the same principle using the language of your API. Use French plurals for French resource names, or follow the relevant grammar rules for Japanese and other languages. The underlying idea remains the same: distinguish collections from singleton resources consistently.

Top comments (0)