Resource-Oriented Design

What is a REST API?

A REST API is modeled as collections of individually-addressable resources:

• Resources are the nouns of the API (e.g., books, channels, players)
• Resources are referenced with their resource names (URIs)
• Resources are manipulated via a small set of methods (HTTP verbs)

The standard HTTP methods for REST APIs are: GET, POST, PUT, PATCH, and DELETE.

Key Insight

Think of resources as the “things” your API manages. The URL identifies what (the resource), and the HTTP verb specifies what to do with it.

---

Resource Design Workflow

When designing a REST API, follow this systematic workflow:

1. Determine resource types: Identify what types of resources your API provides
2. Determine relationships: Define how resources relate to each other
3. Decide naming schemes: Establish resource name conventions based on types and relationships
4. Decide resource schemas: Define resource representations (JSON structure)
5. Assign methods: Map HTTP methods to each resource

---

What is a Resource?

A resource is any piece of data or functionality that clients need to interact with. Resources are the fundamental building blocks of a RESTful API.

Resource Hierarchy

A resource-oriented API is modeled as a resource hierarchy (a tree-like structure). Each node is either:

Node Type	Description	Example
Singleton Resource	A single, specific instance (leaf node)	/books/1, /users/123/profile
Collection Resource	A group of resources of the same type (branch node)	/books, /users/123/orders

Note

A resource can be seen as a directory: it is a container that can contain files (singletons) and subdirectories (sub-collections).

---

Types of Resources

1. Singleton (Simple) Resource

A singleton resource represents a single, specific instance of something.

GET /api/books/1              # A specific book
GET /api/users/123            # A specific user
GET /api/users/123/profile    # User's profile (one-to-one)

Characteristics:

• Represents one specific thing
• Has a unique identifier
• Contains detailed information about that item
• May have its own sub-resources

---

2. Collection Resource

A collection resource contains a list of resources (items) of the same type.

GET /api/books                # All books
GET /api/users                # All users
GET /api/orders               # All orders

Characteristics:

• Contains multiple resources of the same type
• Returns a list or array of items
• Supports create operations (POST)
• Can be paged, sorted, and filtered

---

3. Sub-Collection Resource

A sub-collection is a collection that belongs to a parent resource.

GET /api/books/1/authors      # All authors of book 1
GET /api/users/123/orders     # All orders by user 123
GET /api/projects/5/tasks     # All tasks in project 5

Characteristics:

• Express relationships between resources
• Show ownership or containment
• Provide scoped access to related data

Each sub-resource can be either:

• An instance resource (leaf): /books/1/authors/3
• A collection resource (branch): /books/1/authors

---

Resource Model

A resource model defines what resources your API exposes, what actions can be performed on them, and how they relate to each other. Think of it as translating your application’s data (like database tables or domain objects) into the resources and URLs that clients will interact with.

The diagram below illustrates the aforementioned concepts of in a RESTful API.

---

Resource Relationships

Resources model objects from the application data model and almost always have relationships to other resources. These relationships are often modeled using sub-resources.

Relationship Types

Relation Type	Resources	Meaning
Independent	/projects, /tasks	Tasks can exist with or without a project
Dependent	/projects, /projects/{id}/tasks	Tasks must belong to a project instance
Associative	/users, /projects/{id}/collaborators	Users assigned to a project become collaborators

---

Use Sub-Resources When:

Condition	Example
Child depends on parent	Mission crew depends on mission
Child belongs to parent	Moons belong to a planet
Child lifecycle tied to parent	Order items tied to order

GET /api/missions/apollo-11/crew       # Crew exists within mission context
POST /api/planets/jupiter/moons        # Add moon to Jupiter

---

Use References When:

Condition	Example
Resources exist independently	Astronauts exist without missions
Many-to-many relationships	Astronauts on multiple missions
Relationships change frequently	Spacecraft reassignments

GET /api/astronauts/neil-armstrong

{
  "id": "neil-armstrong",
  "name": "Neil Armstrong",
  "current_mission": "apollo-11",
  "_links": {
    "self": "/api/astronauts/neil-armstrong",
    "current_mission": "/api/missions/apollo-11",
    "all_missions": "/api/astronauts/neil-armstrong/missions"
  }
}

---

Sub-Resource URI Patterns

GET  /{resource}/{resource-id}/{sub-resource}
GET  /{resource}/{resource-id}/{sub-resource}/{sub-resource-id}
POST /{resource}/{resource-id}/{sub-resource}

Examples:

# Get all authors of a specific book
GET /api/books/1/authors

# Get a specific author of a specific book
GET /api/books/1/authors/3

# Add an author to a book
POST /api/books/1/authors

---

Operations on Collections

Collection resources support various operations to manage and retrieve data efficiently.

Standard Operations

Operation	HTTP Method	URI Pattern	Description
List all	GET	/resources	Retrieve all items in collection
Create	POST	/resources	Add a new item to collection
Get one	GET	/resources/{id}	Retrieve a specific item
Update	PUT	/resources/{id}	Replace an entire item
Partial update	PATCH	/resources/{id}	Modify specific fields
Delete	DELETE	/resources/{id}	Remove an item

---

Collection Capabilities

Collections can be:

• Paginated: Return results in manageable chunks
• Sorted: Order results by specific fields
• Filtered: Return only items matching criteria

# Paginated request
GET /api/books?page=2&limit=20

# Sorted request
GET /api/books?sort=title:asc

# Filtered request
GET /api/books?filter=genre:fiction

# Combined
GET /api/books?page=1&limit=10&sort=published_date:desc&filter=author:Tolkien

For detailed implementation guidance, see:

• Pagination
• Filtering
• Sorting

---

Quick Decision Guide

When to Use Each Resource Type

Scenario	Resource Type	Example
Single configuration/settings	Singleton	/users/123/profile
List of similar items	Collection	/products
Items belonging to a parent	Sub-collection	/orders/5/items
One-to-one relationship	Singleton sub-resource	/planets/earth/atmosphere
One-to-many relationship	Sub-collection	/users/123/posts

---

Common Resource Design Patterns

1. Hierarchical Resources

Use hierarchical (sub-resources) when:

• Clear ownership/containment relationship exists
• Child cannot exist without parent
• You need scoped access to related data

/projects/123/tasks/456    # Task 456 belongs to project 123

2. Flat Resources with References

Use flat resources when:

• Resources can exist independently
• Resources are shared across multiple parents
• Deep nesting would become unwieldy

/tasks/456                 # Task exists independently
# Response includes: { "project_id": 123, ... }

---

Hierarchy Depth Guideline

Keep URI hierarchies shallow (2-3 levels maximum):

# Good - clear and manageable
/universities/123/departments/456

# Avoid - too deep
/universities/123/departments/456/courses/789/students/101/grades

---

Summary

For detailed coverage of HTTP methods, see HTTP Verbs. For status codes, see HTTP Status Codes.

Resource-oriented design focuses on:

1. Identifying resources (nouns) rather than actions
2. Organizing resources in a logical hierarchy
3. Using standard HTTP methods for operations
4. Following consistent naming conventions

This approach creates APIs that are:

• Intuitive: Easy to understand and use
• Consistent: Predictable behavior across endpoints
• Scalable: Easy to extend with new resources
• Cacheable: Leverages HTTP caching mechanisms