Designing Resources as Nouns: REST API Modeling Basics

Previously in this course, we covered the foundational concepts of client-server architecture and the importance of statelessness. We also mapped CRUD operations to HTTP methods like GET, POST, PUT, and DELETE.

In this lesson, we shift our focus to the "R" in REST: Representational State Transfer. The core of a well-designed REST API is not the functionality it provides, but the data it manages. To build truly professional APIs, you must stop designing endpoints around what the server does and start designing them around what the server has.

The "Nouns vs. Verbs" Problem

When developers first start building APIs, they often fall into the trap of RPC (Remote Procedure Call) thinking. They create endpoints that describe actions:

• /api/getTasks
• /api/createTask
• /api/deleteTask

While these URLs technically "work," they violate the core REST Principles. REST treats the network as a collection of resources, and resources are represented by nouns. If you find yourself using a verb in your URL (like "get" or "update"), you are likely designing an RPC service, not a REST API.

When you use nouns, the HTTP method handles the action, and the URI handles the identity of the data. Compare the two approaches:

Identifying Resources in Your System

To design a clean API, you must first identify the "nouns" in your domain. A resource is any conceptual object that can be addressed and manipulated.

Think of your system as a database schema. If you are building a Task Manager (our project for this course), you likely have:

1. Users: The people interacting with the app.
2. Tasks: The actual to-do items.
3. Categories: Labels for organizing tasks.

Each of these should be a top-level resource. By naming your endpoints after these entities, you provide an intuitive map for any developer using your API.

Worked Example: From Actions to Resources

Imagine we are building an endpoint to change the status of a task from "pending" to "completed." A common mistake is to name it /api/completeTask.

Following REST principles, we identify the resource (tasks) and the specific instance (123). The action is then performed by sending an update method to that resource:

HTTP
// Instead of POST /api/completeTask/123
// We use:
PATCH /tasks/123
Content-Type: application/json

{
  "status": "completed"
}

By using the PATCH method (which we explored in our lesson on updating API resources), we describe the change to the resource, not the action taken by the server. This makes your API predictable—once a developer knows how to update one resource, they know how to update them all.

Hands-on Exercise

Take the following list of "Action-based" endpoints and convert them into "Resource-based" endpoints using standard REST naming conventions.

1. /api/getAllUsers
2. /api/addNewUser
3. /api/deleteUser
4. /api/updateUserPassword

Hint: Remember that the method (GET, POST, DELETE, PATCH) tells the server what to do with the noun.

Common Pitfalls

• Mixing Styles: Do not use /tasks for one operation and /getTasks for another. Consistency is the hallmark of a professional API.
• Over-nesting: While resources should be hierarchical, avoid making them too deep (e.g., /users/1/tasks/5/comments/3). Stick to one or two levels deep where possible to keep URIs readable.
• Forgetting Plurals: Use plural nouns for collections (e.g., /tasks instead of /task). It is the industry standard for RESTful collection naming.

FAQ

Q: What if I have an action that doesn't fit into CRUD? Sometimes you need to perform an operation that isn't a simple update, like "recalculate invoice." In these rare cases, treat the "calculation" as a temporary sub-resource (e.g., /invoices/123/calculations) or use a clear, verb-based path only when absolutely necessary—but always try to model it as a resource first.

Q: Should I use versioning in my URIs? Yes, but that comes later in the course. For now, focus on establishing the noun-based structure.

Recap

Modeling your API as a set of nouns creates a predictable, self-documenting interface. By mapping actions to HTTP methods and entities to URI paths, you align your code with the REST Principles that power the modern web.

Up next: We will dive into URI Hierarchy and Collections, where we’ll learn how to organize these nouns into a logical, nested structure for our project.