REST API Resources and URLs

In REST, everything is a resource. A user is a resource. A product is a resource. An order is a resource. The URL is the address that points to that resource. Good URL design is one of the clearest signs of a well-designed API.

What Is a Resource?

A resource is any piece of data or business object that your API exposes. Resources are nouns, not verbs. They represent things, not actions.

✅ Good resources (nouns):
   /users
   /products
   /orders
   /invoices

❌ Bad resources (verbs — these are actions, not things):
   /getUsers
   /createProduct
   /deleteOrder
   /fetchInvoice

The HTTP method (GET, POST, DELETE) already expresses the action. The URL should only express the thing being acted upon.

Collections and Single Items

Every resource type has two URL forms: a collection (the group) and a single item (one member of the group).

┌──────────────────────────┬───────────────────────────────────────┐
│  URL                     │  Meaning                              │
├──────────────────────────┼───────────────────────────────────────┤
│  /products               │  All products (collection)            │
│  /products/42            │  The specific product with ID 42      │
│  /users                  │  All users                            │
│  /users/99               │  The user with ID 99                  │
│  /orders                 │  All orders                           │
│  /orders/7               │  Order number 7                       │
└──────────────────────────┴───────────────────────────────────────┘

Always use plural nouns for collection URLs. Use /products, not /product. This is a widely followed convention that makes APIs easier to read.

Nested Resources

When one resource belongs to another resource, nest the URL to show that relationship.

Scenario: An order belongs to a user.
          A review belongs to a product.

┌───────────────────────────────┬───────────────────────────────────┐
│  URL                          │  Meaning                          │
├───────────────────────────────┼───────────────────────────────────┤
│  /users/99/orders             │  All orders for user #99          │
│  /users/99/orders/7           │  Order #7 belonging to user #99   │
│  /products/42/reviews         │  All reviews for product #42      │
│  /products/42/reviews/3       │  Review #3 for product #42        │
└───────────────────────────────┴───────────────────────────────────┘

Visual diagram:
  User (99)
    └── Orders
          └── Order (7)

URL: /users/99/orders/7   ← mirrors this tree structure

Keep nesting to a maximum of two or three levels. Deep nesting becomes hard to read and maintain.

✅ Acceptable:
   /departments/5/employees/12

❌ Too deep — hard to manage:
   /countries/1/states/2/cities/3/streets/4/buildings/5

URL Naming Conventions

Consistent naming makes an API predictable. Use kebab-case (hyphens between words) for multi-word resource names.

✅ Use hyphens (kebab-case):
   /product-categories
   /shipping-addresses
   /order-items

❌ Avoid underscores:
   /product_categories   ← harder to read in links

❌ Avoid camelCase:
   /productCategories    ← looks like code, not a URL

Always use lowercase letters in URLs. URLs are case-sensitive on most servers, and mixing cases causes confusion and broken links.

No File Extensions in URLs

Do not put file extensions like .json or .xml in your URLs. Use the Accept header to negotiate the format instead.

❌ Avoid:
   /products/42.json
   /products/42.xml

✅ Correct:
   /products/42
   (with header: Accept: application/json)

No Trailing Slashes

Trailing slashes at the end of a URL serve no purpose and create inconsistency. Pick one style and stick to it across your entire API.

❌ Inconsistent:
   /products/      (with slash)
   /orders         (without slash)

✅ Consistent (no trailing slash):
   /products
   /orders
   /users/42

Complete URL Design Example: An E-Commerce API

┌────────────────────────────────┬──────────────────────────────────────┐
│  URL                           │  What it represents                  │
├────────────────────────────────┼──────────────────────────────────────┤
│  /products                     │  All products                        │
│  /products/10                  │  Product with ID 10                  │
│  /products/10/reviews          │  All reviews for product 10          │
│  /products/10/reviews/3        │  Review #3 for product 10            │
│  /categories                   │  All product categories              │
│  /categories/2/products        │  All products in category 2          │
│  /users/5/orders               │  All orders placed by user 5         │
│  /users/5/orders/88            │  Order #88 placed by user 5          │
│  /cart                         │  The current user's shopping cart    │
└────────────────────────────────┴──────────────────────────────────────┘

Key Points

• Resources are nouns — URLs name things, not actions
• Use plural nouns for collections: /products, not /product
• Use /resources/{id} to identify a single item
• Nest related resources: /users/99/orders
• Keep nesting shallow — two or three levels maximum
• Use kebab-case, lowercase, and no trailing slashes