Resource-based design thinking in Rest API - Deep Dive

Overview - Resource-based design thinking

What is it?

Resource-based design thinking is a way to build APIs by focusing on resources, which are things or objects that the API manages. Each resource has a unique address (URL) and supports actions like creating, reading, updating, or deleting. This approach helps organize APIs clearly and makes them easy to use and understand. It treats data and functionality as resources that clients can interact with in a simple, consistent way.

Why it matters

Without resource-based design thinking, APIs can become confusing and inconsistent, making it hard for developers to use or maintain them. This approach solves the problem by giving a clear structure and predictable behavior to APIs. It helps teams build APIs that are easier to learn, test, and evolve, which means faster development and better software quality. For users, it means smoother experiences when apps talk to servers.

Where it fits

Before learning this, you should understand basic web concepts like URLs, HTTP methods (GET, POST, PUT, DELETE), and how clients and servers communicate. After mastering resource-based design thinking, you can explore advanced API topics like authentication, versioning, hypermedia controls, and API documentation tools.

Mental Model

Core Idea

An API is like a set of web addresses where each address points to a resource you can act on using standard actions.

Think of it like...

Imagine a library where each book has its own shelf and label (URL). You can borrow (GET), add (POST), update (PUT), or remove (DELETE) books by interacting with their shelves. The library organizes everything clearly so visitors always know where to find or change a book.

┌───────────────┐
│   API Root    │
└──────┬────────┘
       │
       ▼
┌───────────────┐       ┌───────────────┐
│ /users        │       │ /products     │
│ (resource)    │       │ (resource)    │
└──────┬────────┘       └──────┬────────┘
       │                       │
       ▼                       ▼
┌───────────────┐       ┌───────────────┐
│ /users/123    │       │ /products/456 │
│ (single item) │       │ (single item) │
└───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Resources in APIs

Concept: Resources are the main things an API manages, each with a unique URL.

In resource-based design, everything you want to work with is a resource. For example, in a bookstore API, books, authors, and categories are resources. Each resource has a URL like /books or /authors/42. This URL is how clients find and interact with that resource.

Result

You can identify and organize data or objects as resources with clear addresses.

Understanding that APIs revolve around resources helps you see how to structure URLs and organize data logically.

2

Foundation

Using HTTP Methods as Actions

Concept: HTTP methods define what action you want to do on a resource.

The main HTTP methods are GET (read), POST (create), PUT (update), and DELETE (remove). For example, GET /books fetches a list of books, POST /books adds a new book, PUT /books/1 updates book 1, and DELETE /books/1 removes it. These methods give a simple, standard way to work with resources.

Result

You can perform standard actions on resources using HTTP methods.

Knowing that HTTP methods map to actions on resources makes APIs predictable and easier to use.

3

Intermediate

Designing Clear and Consistent URLs

🤔Before reading on: do you think URLs should include verbs like /getBooks or just nouns like /books? Commit to your answer.

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

Good resource-based design uses URLs that name resources, not actions. For example, use /books instead of /getBooks. Actions come from HTTP methods, not URL names. This keeps URLs clean and consistent, making APIs easier to understand and maintain.

Result

APIs have simple, noun-based URLs that clearly represent resources.

Separating actions (HTTP methods) from resource names (URLs) avoids confusion and improves API clarity.

4

Intermediate

Handling Resource Relationships

🤔Before reading on: do you think related resources should be nested in URLs or linked separately? Commit to your answer.

Concept: Resources can relate to each other and this can be shown in URLs or links.

Sometimes resources are connected, like a book having an author. You can show this by nesting URLs, e.g., /authors/5/books to list books by author 5. Alternatively, APIs can provide links inside resource data to related resources. Both ways help clients understand and navigate relationships.

Result

Clients can find related resources easily through URL structure or links.

Representing relationships clearly helps clients explore data naturally and reduces guesswork.

5

Intermediate

Using Status Codes and Responses Properly

Concept: HTTP status codes communicate the result of actions on resources.

When a client requests a resource, the server replies with a status code like 200 (OK), 201 (Created), 404 (Not Found), or 400 (Bad Request). These codes tell the client what happened. For example, after creating a resource with POST, the server returns 201 and the new resource's URL. Proper use of status codes makes APIs clear and reliable.

Result

Clients understand if their requests succeeded or failed and why.

Using standard status codes correctly improves communication between client and server.

6

Advanced

Implementing Statelessness in Resource Design

🤔Before reading on: do you think the server should remember client state between requests? Commit to your answer.

Concept: Each request to a resource should contain all information needed; the server does not keep client state.

Resource-based APIs are stateless, meaning the server treats each request independently. For example, to get a user's data, the client sends all needed info like authentication with each request. This makes APIs scalable and easier to maintain because servers don't store session info.

Result

APIs can handle many clients efficiently without confusion or errors.

Understanding statelessness is key to building scalable and robust APIs.

7

Expert

Using Hypermedia to Guide Resource Interaction

🤔Before reading on: do you think clients should hardcode URLs or discover them dynamically? Commit to your answer.

Concept: Hypermedia lets APIs provide links inside resource data so clients can discover actions and related resources dynamically.

Instead of clients guessing URLs, APIs can include links in responses, like "next", "edit", or "related" URLs. This approach, called HATEOAS, makes APIs more flexible and easier to evolve because clients follow links instead of hardcoded paths. It also improves discoverability and reduces errors.

Result

Clients navigate APIs more naturally and adapt to changes without breaking.

Knowing hypermedia principles helps build APIs that are future-proof and self-describing.

Under the Hood

Resource-based design maps each resource to a unique URL and uses HTTP methods as verbs to act on them. When a client sends a request, the server matches the URL to a resource handler and performs the action indicated by the HTTP method. The server then returns a response with status codes and data. This stateless interaction means the server processes each request independently, relying on the request data alone.

Why designed this way?

This design was created to leverage the existing web infrastructure (HTTP) for APIs, making them simple, scalable, and interoperable. Early web services were complex and inconsistent, so resource-based design brought order by using URLs as resource identifiers and HTTP methods as standard actions. Alternatives like RPC-style APIs were harder to standardize and maintain.

┌───────────────┐
│ Client sends  │
│ HTTP Request  │
│ (URL + Method)│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server matches│
│ URL to       │
│ Resource     │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server performs│
│ action based  │
│ on HTTP method│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Server sends  │
│ response with │
│ status + data │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think resource URLs should include verbs like /createUser? Commit to yes or no before reading on.

Common Belief: Many believe URLs should describe actions, so they include verbs like /createUser or /deleteBook.

Reality: Resource-based design uses nouns for URLs representing resources; actions come from HTTP methods, not URL names.

Why it matters: Using verbs in URLs leads to inconsistent APIs that are harder to learn and maintain.

Quick: Do you think the server should remember client state between requests? Commit to yes or no before reading on.

Common Belief: Some think servers should keep track of client sessions to simplify interactions.

Reality: Resource-based APIs are stateless; each request must contain all information needed for processing.

Why it matters: Stateful servers reduce scalability and increase complexity, causing bugs and performance issues.

Quick: Do you think clients must hardcode all URLs they use? Commit to yes or no before reading on.

Common Belief: Many assume clients should know all URLs upfront and hardcode them in their code.

Reality: Hypermedia allows APIs to provide links dynamically, so clients discover URLs at runtime.

Why it matters: Hardcoding URLs makes clients fragile and hard to update when APIs change.

Quick: Do you think HTTP status codes are optional or decorative? Commit to yes or no before reading on.

Common Belief: Some believe status codes are just extra info and not essential for API communication.

Reality: Status codes are critical for clients to understand request outcomes and handle errors properly.

Why it matters: Ignoring status codes leads to poor error handling and confusing client behavior.

Expert Zone

1

Resource identifiers should be stable and opaque; exposing internal database IDs can cause security and maintenance issues.

2

Using plural nouns for resource collections (e.g., /books) is a convention that improves consistency but is not a strict rule.

3

Partial updates can be handled with PATCH method, which differs from PUT by only changing specified fields, a subtle but important distinction.

When NOT to use

Resource-based design is less suitable for APIs that require complex operations not easily mapped to CRUD actions, such as batch processing or RPC-style commands. In those cases, RPC or GraphQL might be better alternatives.

Production Patterns

In production, APIs often combine resource-based design with authentication tokens, pagination for large collections, filtering and sorting query parameters, and versioning strategies to evolve APIs without breaking clients.

Connections

REST architectural style

Resource-based design thinking is the core principle behind REST APIs.

Understanding resource-based design helps grasp REST's constraints and benefits, enabling better API design.

Database normalization

Both organize data into distinct entities to reduce duplication and improve clarity.

Knowing how databases separate data into tables helps understand why APIs separate concerns into resources.

Urban planning

Just like city planners assign addresses and zones for buildings, resource-based design assigns URLs and organizes resources.

Seeing API URLs as addresses in a city helps appreciate the importance of clear, consistent structure for navigation and growth.

Common Pitfalls

#1 Using verbs in URLs instead of HTTP methods

Wrong approach:

POST /createUser
GET /deleteBook/123

Correct approach:

POST /users
DELETE /books/123

Root cause:

Confusing the role of URLs and HTTP methods leads to mixing actions into URLs, breaking REST principles.

#2 Storing client session state on the server

Wrong approach:

Server keeps user login info in memory between requests without tokens.

Correct approach:

Client sends authentication token with each request; server treats requests independently.

Root cause:

Misunderstanding statelessness causes scalability and reliability problems.

#3 Hardcoding all URLs in client code

Wrong approach:

Client code uses fixed URLs like /api/v1/users/123 without flexibility.

Correct approach:

Client discovers URLs from API responses using hypermedia links.

Root cause:

Ignoring hypermedia principles makes clients fragile and hard to maintain.

Key Takeaways

Resource-based design thinking organizes APIs around resources identified by URLs and manipulated using standard HTTP methods.

Using nouns for URLs and verbs for HTTP methods keeps APIs clear, consistent, and easy to use.

Statelessness ensures each request is independent, improving scalability and reliability.

Proper use of HTTP status codes and hypermedia links enhances communication and flexibility between clients and servers.

Understanding resource relationships and URL design helps build intuitive and maintainable APIs.