Thinking in Resources: The Noun-Based Approach to API Design

The most fundamental shift when learning REST is learning to think in resources. Traditional programming thinks in functions and actions. REST thinks in things — nouns that represent real-world entities. This lesson teaches you how to identify resources, model their relationships, and design APIs that feel natural.

---

1. What Is a Resource?

A resource is any entity or object that your system manages. Resources are nouns: users, posts, orders, invoices, products, messages.

Every resource has:

• A unique identifier (usually an ID)
• A set of attributes (properties/fields)
• Relationships to other resources
• A URL that addresses it

graph TD
    A[Resource: User] --> B["ID: 42"]
    A --> C["Attributes:<br/>name, email, role"]
    A --> D["Relationships:<br/>has many Posts<br/>has many Orders"]
    A --> E["URL: /users/42"]

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style C fill:#0891b2,color:#fff
    style D fill:#059669,color:#fff
    style E fill:#d97706,color:#fff

---

2. Identifying Resources from Requirements

When designing an API, start by extracting the nouns from the requirements.

Example: Blog Platform

Requirements: "Users can create blog posts, add tags to posts, leave comments on posts, and follow other users."

Nouns (Resources):

• Users
• Posts
• Tags
• Comments
• Followers (Follow relationships)

Resulting Endpoints:

/users
/users/:id
/posts
/posts/:id
/posts/:id/tags
/posts/:id/comments
/users/:id/followers
/users/:id/following

Example: E-Commerce System

Requirements: "Customers browse products in categories, add items to a cart, place orders, and leave reviews."

Resources:

• Customers → /customers
• Products → /products
• Categories → /categories
• Carts → /carts
• Cart Items → /carts/:id/items
• Orders → /orders
• Order Items → /orders/:id/items
• Reviews → /products/:id/reviews

graph TD
    A[Customer] -->|browses| B[Products]
    B -->|belongs to| C[Category]
    A -->|has| D[Cart]
    D -->|contains| E[Cart Items]
    E -->|references| B
    A -->|places| F[Orders]
    F -->|contains| G[Order Items]
    G -->|references| B
    A -->|writes| H[Reviews]
    H -->|for| B

    style A fill:#4f46e5,color:#fff
    style B fill:#0891b2,color:#fff
    style F fill:#d97706,color:#fff

---

3. Resource Representations

A resource can have multiple representations — different ways to format the same data. JSON is the most common, but the same resource might be available as XML, CSV, or HTML.

The Same Resource in Different Formats

JSON:

{
  "id": 42,
  "name": "Clean Code",
  "price": 34.99,
  "author": "Robert Martin"
}

XML:

<book>
  <id>42</id>
  <name>Clean Code</name>
  <price>34.99</price>
  <author>Robert Martin</author>
</book>

The Accept header in the request tells the server which format you want.

---

4. Collections vs Individual Resources

REST distinguishes between a collection of resources and an individual resource:

Type	URL Pattern	Returns
Collection	/users	Array of user objects
Individual	/users/42	Single user object

Collection Behavior

# GET collection → array
curl https://jsonplaceholder.typicode.com/users
# Returns: [{...}, {...}, {...}, ...]

# POST to collection → create in collection
curl -X POST https://jsonplaceholder.typicode.com/users -d '...'
# Creates a new user and adds it to the collection

Individual Resource Behavior

# GET individual → single object
curl https://jsonplaceholder.typicode.com/users/1
# Returns: {...}

# PUT individual → replace that resource
curl -X PUT https://jsonplaceholder.typicode.com/users/1 -d '...'

# DELETE individual → remove that resource
curl -X DELETE https://jsonplaceholder.typicode.com/users/1

---

5. Modeling Relationships

Resources rarely exist in isolation. They have relationships:

One-to-Many

A user has many posts:

GET /users/42/posts     → All posts by user 42
POST /users/42/posts    → Create a post for user 42

Many-to-Many

A post can have many tags, and a tag can belong to many posts:

GET /posts/7/tags       → All tags on post 7
POST /posts/7/tags      → Add a tag to post 7
DELETE /posts/7/tags/3  → Remove tag 3 from post 7

GET /tags/5/posts       → All posts with tag 5

Nested vs Flat

You can represent relationships either way:

Nested (hierarchical):

/users/42/posts/7/comments

Flat (with query parameters):

/comments?postId=7&userId=42

Rule of thumb: Nest to a maximum of 2 levels. Beyond that, use query parameters.

/users/42/posts           ← Good: 2 levels
/users/42/posts/7         ← Good: 2 levels with ID
/users/42/posts/7/comments/15/likes  ← Too deep!
/likes?commentId=15       ← Better: flattened

---

6. Sub-Resources and Actions

Sometimes a resource has sub-resources that only make sense in context:

/orders/300/items         → Items in order 300
/orders/300/invoice       → Invoice for order 300
/users/42/avatar          → User 42's profile picture
/posts/7/likes            → Likes on post 7

For actions that do not map cleanly to CRUD, use a verb sub-resource:

POST /orders/300/cancel       → Cancel order 300
POST /users/42/verify-email   → Trigger email verification
POST /reports/generate        → Generate a report

These break the "no verbs" rule slightly, but it is the accepted convention for non-CRUD operations.

---

7. Resource Naming Conventions

Rule	Bad	Good
Use plural nouns	/user	/users
Use lowercase	/Users	/users
Use hyphens for multi-word	/user_profiles	/user-profiles
No file extensions	/users.json	/users
No trailing slashes	/users/	/users
No verbs	/getUsers	/users
Consistent pluralization	/user, /posts	/users, /posts

---

Summary and Key Takeaways

1. Resources are nouns — things, entities, objects in your system.
2. Extract nouns from requirements to identify your resources.
3. Collections return arrays; individual resources return objects.
4. Model relationships using nested URLs (max 2 levels) or query parameters.
5. Use sub-resources for related data and verb sub-resources for non-CRUD actions.
6. Follow consistent naming conventions: plural, lowercase, hyphens.

---

Lesson Review Quiz