Naming REST API Resources the Right Way

The two, often cited, most difficult things in Computer Science are cache invalidation and naming things. I'm afraid both are unavoidable when building web applications and APIs are also part of web applications. In this post we will focus on the later as resource names are not internal identifiers. They are part of a public contract that developers will read, depend on and sometimes even memorize.

In REST, a resource name plays several roles at once. It names the concept, identifies it uniquely, and often locates it within the system. This makes naming decisions especially important.

What good resource name look like

A good resource name should be:

• Intuitive
• Self descriptive
• Stable over time

If someone sees a URL without any documentation, they should be able to make a reasonable guess about what it represents.

For example:

/books

Clearly represents a collection of books. Adding an identifier narrows it down to a specific instance:

/books/VE101

The structure reads naturally. From the books collection, retrieve the book identified by ID VE101.

Plural versus singular

There is ongoing debate about whether resource names should be singular or plural. In practice, plural nouns have become the dominant convention.

Using plural names keeps URLs consistent. The same base path represents both collections and individual resources. This avoids switching between /book and /books depending on context.

Consistency matters more than theoretical rigorous correctness. Once a convention is chosen, it should be applied everywhere and not changed. I always use plurals when designing APIs.

Avoid leaking internal structure

Resource names should reflect domain concepts, not internal implementation details. Names derived from class names or database tables often expose information that is irrelevant or harmful to API consumers.

For example, if the backend has separate classes called BookWaitingList and ClubWaitingList, exposing both as separate resources may be unnecessary. From an API perspective, both represent waiting lists associated with different parent resources.

So, instead of

/book-waiting-list
/club-waiting-list

A cleaner design would be:

/books/{id}/waiting-list
/clubs/{id}/waiting-list

The relationship provides the necessary context. The resource name remains simple, consistent and overall intuitive

Choosing readable separators

Multi word resource names should be readable. Whether you choose hyphen separated words, camel case, or another convention is less important than consistency.

Once a convention is selected, it must be applied uniformly. Mixing styles makes APIs harder to read, maintain and consume.

Resource names are hard to change

Unlike internal code, resource names are difficult to refactor once published. Changing a URL can break clients, integrations, and documentation.

This is why resource naming deserves careful consideration early on. When changes are unavoidable, backward compatibility mechanisms such as redirects or versioning should be used to minimize disruption.

Thoughtful naming is an investment. It reduces confusion, improves developer experience, and increases the longevity of your API.

If you like what you've read so far or resonate with my opinions, why don't you subscribe?. It's free!