Noun-based resource naming in Rest API - Deep Dive

Overview - Noun-based resource naming

What is it?

Noun-based resource naming is a way to name parts of a web API using nouns that represent things or objects. Instead of using verbs or actions in the URL, it uses names of resources like 'users' or 'books'. This makes the API easier to understand and consistent. It helps clients know what data they are working with just by looking at the URL.

Why it matters

Without noun-based naming, APIs can become confusing and inconsistent, making it hard for developers to guess how to use them. If URLs used verbs or mixed styles, clients would struggle to predict endpoints, slowing down development and causing errors. Using nouns creates a clear, predictable structure that improves communication between developers and systems.

Where it fits

Before learning noun-based resource naming, you should understand basic web concepts like URLs and HTTP methods (GET, POST, etc.). After this, you can learn about RESTful API design principles and how to handle actions and relationships between resources.

Mental Model

Core Idea

An API URL should name the thing you want to work with, not the action you want to perform.

Think of it like...

It's like a library catalog: you look up books by their titles (nouns), not by what you want to do with them.

API URL Structure:

  /resources
  /resources/{id}
  /resources/{id}/subresources

Where 'resources' and 'subresources' are nouns representing things.

Build-Up - 7 Steps

1

Foundation

Understanding API URLs as resource names

Concept: API URLs should represent resources using nouns, not actions or verbs.

In REST APIs, URLs identify resources like 'users', 'orders', or 'products'. For example, '/users' refers to the collection of all users, and '/users/123' refers to a specific user with ID 123. This naming style uses nouns to clearly show what data is being accessed.

Result

You can tell what data an API endpoint works with just by reading the URL.

Understanding that URLs name things rather than actions helps you design APIs that are intuitive and easy to use.

2

Foundation

Mapping HTTP methods to resource actions

Concept: HTTP methods (GET, POST, PUT, DELETE) define what action to perform on the noun resource named in the URL.

Instead of putting actions in the URL, REST uses HTTP methods: - GET /users fetches users - POST /users creates a new user - PUT /users/123 updates user 123 - DELETE /users/123 deletes user 123 This keeps URLs simple and consistent.

Result

You separate the 'what' (resource) from the 'how' (action), making APIs cleaner.

Knowing that HTTP methods carry the action meaning frees URLs to focus on naming resources clearly.

3

Intermediate

Using plural nouns for resource collections

Concept: Resource names should be plural nouns to represent collections of items consistently.

Use plural nouns like '/books' or '/orders' to represent collections. A single item is accessed by adding its ID, e.g., '/books/45'. This convention avoids confusion and keeps naming uniform across the API.

Result

API users can predict URLs for collections and single items easily.

Choosing plural nouns for collections creates a natural and predictable URL pattern that scales well.

4

Intermediate

Nesting resources to show relationships

Concept: You can nest resource nouns in URLs to express relationships between resources.

For example, '/users/123/orders' shows orders belonging to user 123. This nesting uses nouns to represent the hierarchy or connection between resources, making the API structure clear.

Result

Clients understand how resources relate without extra explanation.

Using nested nouns in URLs models real-world relationships, improving API clarity and usability.

5

Intermediate

Avoiding verbs and actions in URLs

🤔Before reading on: Do you think including verbs like '/getUser' or '/createOrder' in URLs is good practice? Commit to your answer.

Concept: URLs should not contain verbs or actions; these belong in HTTP methods or request bodies.

Avoid URLs like '/getUser' or '/createOrder'. Instead, use '/users' with GET or POST methods. This keeps URLs clean and consistent, and separates resource naming from actions.

Result

APIs become easier to learn and maintain because URLs follow a simple noun-based pattern.

Recognizing that verbs in URLs cause confusion helps you design APIs that follow REST principles and improve developer experience.

6

Advanced

Handling complex actions with noun-based URLs

🤔Before reading on: Can complex actions like 'approve order' be represented with just nouns and HTTP methods? Commit to your answer.

Concept: Even complex actions can be modeled using noun-based URLs combined with HTTP methods or sub-resources.

For actions like approving an order, use URLs like '/orders/123/approval' with POST or PATCH methods. This treats 'approval' as a sub-resource or state change, keeping URLs noun-based while supporting complex workflows.

Result

You maintain noun-based naming while enabling rich API behaviors.

Understanding how to model actions as resources or state changes preserves noun-based naming and RESTful design in complex cases.

7

Expert

Balancing noun-based naming with practical exceptions

🤔Before reading on: Is strict noun-only naming always the best choice for every API endpoint? Commit to your answer.

Concept: Sometimes, pragmatic exceptions to noun-based naming improve clarity or performance, especially for non-resource operations.

For example, search endpoints might use '/search' or '/users/search' even though 'search' is a verb. This is accepted when it simplifies client usage or matches common patterns. Experts balance purity with usability.

Result

You learn when to bend rules for better real-world API design.

Knowing when to relax strict noun-based naming helps you build APIs that are both RESTful and practical.

Under the Hood

When a client sends a request, the server uses the URL to identify the resource (noun) and the HTTP method to determine the action. The server then processes the request accordingly, mapping URLs to data models or database entities. This separation allows caching, security, and routing to work efficiently because URLs consistently represent resources.

Why designed this way?

Noun-based naming was designed to make APIs predictable and uniform. Early web APIs mixed verbs and nouns, causing confusion. REST principles emphasized resources as nouns to align with the web's architecture, enabling better scalability, caching, and simplicity.

Client Request
   │
   ▼
[URL: /resources/{id}] + [HTTP Method]
   │
   ▼
Server Router
   │
   ▼
Resource Handler (maps noun to data)
   │
   ▼
Action Executor (based on HTTP method)
   │
   ▼
Response

Myth Busters - 4 Common Misconceptions

Quick: Do you think verbs in URLs make APIs easier to understand? Commit to yes or no before reading on.

Common Belief: Including verbs like '/getUser' or '/updateOrder' in URLs makes the API clearer because it says exactly what happens.

Reality: Verbs in URLs confuse clients because HTTP methods already define actions. Mixing verbs in URLs breaks consistency and predictability.

Why it matters: APIs with verbs in URLs are harder to learn, maintain, and can cause errors when clients guess endpoints.

Quick: Do you think singular nouns are better than plural nouns for resource names? Commit to your answer.

Common Belief: Using singular nouns like '/user' is simpler and more natural than plural '/users'.

Reality: Plural nouns better represent collections and make URL patterns consistent, especially when accessing multiple items or single items by ID.

Why it matters: Using singular nouns can confuse clients about whether the URL is a collection or single item, leading to misuse.

Quick: Do you think nesting resources too deeply in URLs is always good? Commit to yes or no.

Common Belief: The more nested the URL, the clearer the relationships between resources.

Reality: Excessive nesting makes URLs long and complex, hurting readability and performance. Shallow nesting is preferred.

Why it matters: Deeply nested URLs can be hard to use and maintain, causing client errors and slower responses.

Quick: Do you think all API actions must be represented as noun-based URLs? Commit to your answer.

Common Belief: Every action can and should be modeled as a noun-based resource.

Reality: Some actions like search or login are better handled as exceptions with verb-like endpoints for clarity and usability.

Why it matters: Forcing noun-only URLs in all cases can make APIs awkward and harder to use.

Expert Zone

1

Resource names should be consistent across the API to avoid confusion, even if some resources seem similar.

2

Using sub-resources to represent state changes or actions can keep URLs noun-based but requires careful design to avoid complexity.

3

Sometimes, query parameters complement noun-based URLs to filter or modify resource views without adding verbs.

When NOT to use

Strict noun-based naming is not ideal for RPC-style APIs or when the API needs to expose complex commands that don't map well to resources. Alternatives include RPC endpoints or GraphQL, which focus on actions or queries rather than resource nouns.

Production Patterns

In real-world APIs, noun-based naming is combined with versioning (e.g., /v1/users), pagination, filtering via query parameters, and sometimes pragmatic verb-like endpoints for operations like authentication or search.

Connections

RESTful API design

Noun-based resource naming is a core principle that RESTful API design builds upon.

Understanding noun-based naming helps grasp the broader REST philosophy of treating everything as a resource.

Database modeling

Resource nouns in APIs often correspond to tables or entities in databases.

Knowing database design helps in choosing clear, consistent resource names that map naturally to data structures.

Library cataloging systems

Both organize items by nouns (titles, authors) rather than actions.

Seeing how libraries organize information helps appreciate why noun-based naming makes APIs easier to navigate.

Common Pitfalls

#1 Using verbs in URLs instead of nouns.

Wrong approach:

GET /getUser
POST /createOrder
PUT /updateProduct/123

Correct approach:

GET /users
POST /orders
PUT /products/123

Root cause:

Confusing the role of URLs and HTTP methods, leading to mixing actions into URLs.

#2 Using singular nouns inconsistently for collections.

Wrong approach:

GET /user
GET /user/123

Correct approach:

GET /users
GET /users/123

Root cause:

Not distinguishing between a collection and a single resource in naming.

#3 Over-nesting resources making URLs too long.

Wrong approach:

GET /users/123/orders/456/items/789/details

Correct approach:

GET /orders/456/items/789/details

Root cause:

Trying to express all relationships in the URL instead of using IDs and references.

Key Takeaways

Noun-based resource naming means URLs name things, not actions, making APIs clearer and more predictable.

HTTP methods carry the action meaning, so URLs stay simple and consistent by using nouns.

Using plural nouns for collections and nesting resources to show relationships helps clients understand API structure.

Avoid verbs in URLs to prevent confusion and maintain RESTful design principles.

Pragmatic exceptions exist, but knowing when to apply them keeps APIs both usable and well-designed.