Avoiding verbs in URLs in Rest API - Deep Dive

Overview - Avoiding verbs in URLs

What is it?

Avoiding verbs in URLs means designing web addresses that use nouns instead of action words. This style focuses on resources, like users or products, rather than actions like 'create' or 'delete'. It helps make URLs clear, consistent, and easy to understand. This approach is common in REST API design.

Why it matters

Using verbs in URLs can confuse users and developers because URLs should represent things, not actions. Without this rule, APIs become harder to use and maintain, leading to mistakes and slower development. Clear, noun-based URLs improve communication and make APIs more predictable and user-friendly.

Where it fits

Learners should first understand basic HTTP methods like GET, POST, PUT, and DELETE. After mastering noun-based URLs, they can learn advanced REST concepts like HATEOAS and API versioning. This topic fits in the journey of designing clean, scalable web APIs.

Mental Model

Core Idea

URLs should name resources (things) while HTTP methods define actions on those resources.

Think of it like...

Think of a library catalog: the catalog lists books by title (nouns), and you use different actions like borrowing or returning separately. The catalog itself doesn't say 'borrow-book' but just 'book'.

┌─────────────┐       ┌───────────────┐
│   URL (noun)│──────▶│ HTTP Method   │
│ /users/123  │       │ GET, POST...  │
└─────────────┘       └───────────────┘

URL names the resource, HTTP method names the action.

Build-Up - 7 Steps

1

Foundation

Understanding URLs as Resource Names

Concept: URLs should represent resources, which are things or data entities, not actions.

In REST APIs, URLs like /users or /products point to collections or single items. They are nouns describing what you want to access. For example, /users/123 means user with ID 123.

Result

You get a clear, consistent way to identify data entities in your API.

Understanding that URLs name resources helps separate the 'what' (resource) from the 'how' (action), making APIs easier to design and use.

2

Foundation

Role of HTTP Methods in Actions

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

GET /users/123 fetches user data, POST /users creates a new user, PUT /users/123 updates user 123, DELETE /users/123 removes user 123. The URL stays the same; the method changes the action.

Result

Actions are cleanly separated from resource names, avoiding confusion.

Knowing that HTTP methods carry the action meaning prevents mixing verbs into URLs, which keeps APIs intuitive.

3

Intermediate

Why Verbs in URLs Cause Problems

🤔Before reading on: do you think including verbs in URLs makes APIs clearer or more confusing? Commit to your answer.

Concept: Including verbs in URLs mixes resource identification with actions, leading to redundancy and inconsistency.

URLs like /createUser or /deleteProduct repeat the action already expressed by HTTP methods. This causes confusion, harder maintenance, and breaks REST principles.

Result

APIs with verbs in URLs are less predictable and harder to document or automate.

Understanding the confusion verbs cause in URLs helps you appreciate the clean separation REST encourages.

4

Intermediate

Using Nouns with Query Parameters for Actions

Concept: Sometimes actions need extra details; these can be passed as query parameters, not verbs in URLs.

For example, to filter users by status, use GET /users?status=active instead of /getActiveUsers. This keeps the URL noun-based and uses parameters to specify details.

Result

APIs remain clean and flexible while supporting complex queries.

Knowing how to use query parameters preserves noun-only URLs and avoids verb clutter.

5

Intermediate

Handling Complex Actions with Sub-resources

🤔Before reading on: do you think complex actions should be verbs in URLs or modeled differently? Commit to your answer.

Concept: Complex actions can be modeled as sub-resources or state changes, not verbs in URLs.

For example, to activate a user, use POST /users/123/activation instead of /activateUser. This treats activation as a resource representing the activation state.

Result

APIs stay RESTful and expressive without breaking noun-only URL rules.

Understanding sub-resources lets you model actions cleanly without verbs in URLs.

6

Advanced

Exceptions and Pragmatic Use of Verbs

🤔Before reading on: do you think verbs in URLs are always wrong or sometimes acceptable? Commit to your answer.

Concept: In some cases, verbs in URLs are pragmatic for non-CRUD actions or RPC-style APIs.

For example, /login or /logout are verbs but often used because they represent operations not fitting resource models. However, these should be exceptions, not the norm.

Result

You learn when to bend rules for practical reasons without losing API clarity.

Knowing when verbs are acceptable prevents dogmatic design and supports real-world API needs.

7

Expert

Impact on API Evolution and Tooling

🤔Before reading on: do you think verb-free URLs affect API versioning and tooling positively or negatively? Commit to your answer.

Concept: Verb-free URLs improve API evolution, caching, and tooling support by keeping resource identity stable and actions separate.

Tools like API gateways, caches, and documentation generators rely on consistent resource URLs. Verb-free URLs make these tools more effective and reduce breaking changes during API updates.

Result

APIs become easier to maintain, scale, and integrate with other systems.

Understanding this impact helps design APIs that last and work well with modern infrastructure.

Under the Hood

When a client sends a request, the server uses the URL to identify the resource and the HTTP method to determine the action. The server routes the request to the correct handler based on this separation. This design allows caching GET requests by URL and simplifies permission checks by resource.

Why designed this way?

REST was designed to separate resource identification from actions to improve scalability, simplicity, and uniformity. Early web architecture inspired this by treating URLs as resource locators and HTTP methods as verbs. Alternatives mixing verbs in URLs led to inconsistent APIs and harder maintenance.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Client      │──────▶│   Server      │──────▶│ Resource Logic│
│ (URL + Method)│       │ (Router)      │       │ (CRUD actions)│
└───────────────┘       └───────────────┘       └───────────────┘

URL identifies resource → HTTP method defines action → Server executes logic

Myth Busters - 4 Common Misconceptions

Quick: Do you think verbs in URLs make APIs more intuitive? Commit yes or no.

Common Belief: Including verbs in URLs makes the API's purpose clearer because the action is explicit.

Reality: Verbs in URLs duplicate the meaning of HTTP methods, causing confusion and inconsistency.

Why it matters: This misconception leads to messy APIs that are harder to learn and maintain.

Quick: Do you think URLs should always be verbs to describe actions? Commit yes or no.

Common Belief: URLs should describe what the API does, so verbs belong in URLs.

Reality: URLs should identify resources; actions belong in HTTP methods or request bodies.

Why it matters: Mixing actions into URLs breaks REST principles and complicates client-server communication.

Quick: Do you think query parameters are for actions or filters? Commit your answer.

Common Belief: Query parameters are just for filtering data, not for specifying actions.

Reality: Query parameters can specify details of actions without adding verbs to URLs.

Why it matters: Misusing query parameters limits API flexibility and leads to verb-like URLs.

Quick: Do you think exceptions like /login break REST design badly? Commit yes or no.

Common Belief: Any verb in a URL breaks REST and should be avoided at all costs.

Reality: Some verbs are pragmatic exceptions for operations that don't fit resource models.

Why it matters: Ignoring exceptions can lead to awkward or overly complex API designs.

Expert Zone

1

Some actions are better modeled as state changes on sub-resources rather than verbs, improving clarity and caching.

2

Verb-free URLs improve HTTP caching effectiveness because URLs uniquely identify resources without action ambiguity.

3

API documentation and client code generation tools rely on noun-based URLs to generate consistent interfaces.

When NOT to use

Avoid strict noun-only URLs when implementing RPC-style APIs or operations like authentication where verbs like /login are clearer. In such cases, use clear documentation and consistent patterns to avoid confusion.

Production Patterns

In production, APIs use noun-based URLs with HTTP methods for CRUD operations, sub-resources for complex actions, and query parameters for filtering. Exceptions like /login are isolated and well-documented. This pattern supports scalability, caching, and client compatibility.

Connections

HTTP Methods

Builds-on

Understanding HTTP methods is essential because they carry the action meaning that URLs avoid expressing with verbs.

REST API Design

Core principle

Avoiding verbs in URLs is a fundamental REST design principle that ensures APIs are uniform and scalable.

Library Cataloging Systems

Analogous pattern

Like library catalogs that list books by title (nouns) and separate borrowing actions, URLs name resources while HTTP methods handle actions.

Common Pitfalls

#1 Using verbs in URLs causing redundancy and confusion.

Wrong approach:

POST /createUser with body {name: 'Alice'}

Correct approach:

POST /users with body {name: 'Alice'}

Root cause:

Misunderstanding that HTTP methods already express actions, so verbs in URLs are unnecessary.

#2 Trying to encode complex actions as verbs in URLs instead of resources.

Wrong approach:

POST /activateUser/123

Correct approach:

POST /users/123/activation

Root cause:

Not modeling actions as sub-resources leads to verb misuse in URLs.

#3 Using query parameters as verbs instead of filters.

Wrong approach:

GET /users?action=delete&id=123

Correct approach:

DELETE /users/123

Root cause:

Confusing query parameters as action triggers rather than filters or modifiers.

Key Takeaways

URLs should name resources using nouns, while HTTP methods specify actions on those resources.

Avoiding verbs in URLs keeps APIs consistent, predictable, and easier to maintain.

Complex actions can be modeled as sub-resources or state changes instead of verbs in URLs.

Some pragmatic exceptions exist, but they should be limited and well-documented.

This design improves caching, tooling support, and API evolution over time.