Plural vs singular resource names in Rest API

Introduction

Using plural or singular names for resources helps keep your API clear and easy to understand.

When designing URLs for a list of items, like all users or all books.

When referring to a single item, like one user or one book.

When you want your API to be consistent and predictable for developers.

When you want to avoid confusion about whether an endpoint returns one or many items.

Syntax

Rest API

/resources  (plural for collections)
/resources/123   (for single item)

Use plural names for endpoints that return multiple items, like /users.

Use plural names when the endpoint deals with a single item, often with an ID, like /users/123.

Examples

Plural /books is for the collection. /books/45 (with ID) is for one book.

Rest API

/books       (returns list of books)
/books/45    (returns book with ID 45)

Plural /users for all users, /users/7 (with ID) for one user.

Rest API

/users       (returns list of users)
/users/7     (returns user with ID 7)

Sample Program

This example shows how plural /cars returns many cars, and /cars/10 returns one car.

Rest API

GET /cars       # returns list of cars
GET /cars/10    # returns car with ID 10

# Example response for GET /cars
[
  {"id": 1, "model": "Sedan"},
  {"id": 10, "model": "SUV"}
]

# Example response for GET /cars/10
{
  "id": 10,
  "model": "SUV"
}

Important Notes

Most APIs prefer plural resource names for collections to keep things consistent.

Plural names are usually used when specifying a single resource with an ID.

Consistency is more important than which you choose, so pick one style and stick with it.

Summary

Use plural names for endpoints that return lists of items.

Use plural names with ID when accessing a single item by ID.

Keep your API naming consistent to make it easier for others to use.