KAHIBARO
Discord Login Register ☰
☰

7.3 Resources and Endpoints

Table of Contents

Understanding Resources and Endpoints

In REST, almost everything starts with two ideas: resources and endpoints. If you understand these well, the rest of REST becomes much easier.

This chapter focuses only on what resources and endpoints are, how to design them, and many concrete examples. Other topics, like HTTP methods and status codes, have their own chapters.

What Is a Resource?

A resource is an object or concept in your system that you want to expose through your API.

You can think of a resource as "a kind of thing" that your API works with.

Some common resource examples:

DomainPossible resources
Task managerusers, tasks, projects, comments
E commerceproducts, categories, orders, carts, reviews
Blogging platformposts, users, comments, tags
School systemstudents, courses, enrollments, teachers
Social networkusers, posts, likes, followers, messages

You rarely expose every internal object as a resource. You choose the things that make sense to clients of the API.

Key points about resources:

Important rule:
Think first about resources (the nouns), then about how to operate on them (the verbs / HTTP methods).
Do not start with actions like /createUser or /deleteOrder. Design the things first.

Identifying Resources

To identify resources in a system, imagine you are explaining your application without any code.

Example: Task management app. You might say:

From this description, you can spot the nouns:

These are good candidates for resources.

Exercise in your mind

Take a simple "online course platform" and list candidates:

Nouns:

You do not have to expose all of them. You choose what is useful:

What Is an Endpoint?

An endpoint is a URL path that represents a resource (or resources) in your API.

Formally, an endpoint is the combination of:

You will study methods in detail in other chapters, but for now you can think:

Examples of endpoints:

EndpointWhat it refers to
GET /usersthe collection of users
POST /usersthe collection of users (create a new one)
GET /users/10a single user with id 10
GET /projects/5/taskstasks that belong to project 5
DELETE /orders/99the order with id 99

Notice that the path itself is usually just nouns.
The action is expressed by the HTTP method, not by the path.

Important rule:
Endpoints should use nouns in URLs and HTTP methods for actions, for example:

  • POST /users (create user)
    Not: /createUser

Collections vs Individual Resources

Usually, each resource type has:

Collection endpoints

A collection is the list or set of all items of a resource.

Typical patterns:

The same applies for other resources:

ResourceCollection endpoints
usersGET /users, POST /users
ordersGET /orders, POST /orders
productsGET /products, POST /products
commentsGET /comments, POST /comments

Later, you may add query parameters for filtering, pagination, and so on, but the base collection endpoint is usually just the plural noun.

Single resource endpoints

A single resource endpoint refers to one specific item, often by ID.

Typical patterns:

Examples for different resources:

ResourceSingle resource endpoints (examples)
userGET /users/123, PATCH /users/123
orderGET /orders/55, DELETE /orders/55
productGET /products/999, PUT /products/999

Here {task_id}, {user_id}, {order_id} are path parameters that identify a particular item of the resource.

You will learn path parameters in more detail in another chapter. For now, just understand that they are part of the URL and used to uniquely identify a resource instance.

Naming Resources and Endpoints

Naming is important for a clean API. There is no single universal rulebook, but there are strong conventions that most APIs follow.

Use plural nouns for collections

Most APIs use plural nouns for the main collection endpoints.

Good examples:

Then single items are under those collections:

Some APIs use singular nouns (like /user), but plural is far more common and easier to reason about:

Important rule:
Use plural nouns for top level resource collections: /users, /orders, /products.
Keep it consistent across your entire API.

Use lowercase and hyphens

For readability and consistency:

Examples:

PreferAvoid
/user-profiles/userProfiles
/order-items/order_items
/product-reviews/ProductReviews

You may see underscores in some APIs, but hyphens are more common in URL paths.

Avoid verbs in URLs

The path represents resources, which are nouns, not actions.

Good:

Avoid:

The HTTP method already tells you the action. The endpoint path should describe what the method is applied to.

Consistent naming patterns

Try to keep resource names consistent:

Hierarchical Endpoints and Subresources

Some resources have a natural parent child relationship. For example:

In these cases, you can express the relationship in your endpoints.

Parent-child collections

Examples:

Here, tasks and comments are often called subresources or nested resources of the parent.

Individual child resources

Sometimes you also access an individual child resource through the parent.

For example:

Technically, GET /tasks/5 and GET /projects/10/tasks/5 might refer to the same task.
Some APIs:

As a beginner, a simple and common choice is:

When to nest, when not to nest

Nesting is useful when:

Too much nesting becomes confusing:

A simple guideline:

Relationships and Linking Resources

Resources often have relationships with each other.

Common relationships:

You can represent these relationships in different ways.

Example: Users and Orders

Resources:

Possible endpoints:

PurposeEndpoint
List all usersGET /users
Get one userGET /users/{user_id}
List all ordersGET /orders
Get one orderGET /orders/{order_id}
List orders for a specific userGET /users/{user_id}/orders

The API response for GET /users/1 might include links to related resources, for example:

json 
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "links": {
    "self": "/users/1",
    "orders": "/users/1/orders"
  }
}

This is one way of making relationships discoverable.

Example: Many to many with join resources

Sometimes, a relationship itself becomes its own resource.

Example: A user can enroll in many courses, and a course has many users. The enrollment can be a resource:

Possible endpoints:

Here, enrollments is a resource that connects two other resources.

Representing a Resource

An endpoint returns a representation of a resource, usually in JSON.

Example resource: task

A typical JSON representation:

json 
{
  "id": 42,
  "title": "Write API chapter",
  "description": "Explain resources and endpoints",
  "status": "in_progress",
  "project_id": 3,
  "created_at": "2026-08-27T10:15:00Z",
  "updated_at": "2026-08-27T11:00:00Z"
}

Different endpoints can return different views of the same resource:

json 
[
  {
    "id": 42,
    "title": "Write API chapter",
    "status": "in_progress"
  },
  {
    "id": 43,
    "title": "Review examples",
    "status": "todo"
  }
]

You will study response models and validation in other chapters. Here, focus on the idea that each endpoint is tied to a resource and returns a sensible representation of it.

Examples of Resource and Endpoint Design

To make these ideas concrete, look at some mini APIs.

Example 1: Simple Task API

Resources:

Endpoints:

PurposeEndpoint
List all tasksGET /tasks
Create a new taskPOST /tasks
Get a single taskGET /tasks/{task_id}
Update a taskPATCH /tasks/{task_id}
Delete a taskDELETE /tasks/{task_id}
List tasks for a specific projectGET /projects/{project_id}/tasks
List projectsGET /projects
Create a projectPOST /projects
Get a projectGET /projects/{project_id}

Notice:

No verbs in URLs, only nouns.

Example 2: E commerce API

Resources:

Some endpoints:

PurposeEndpoint
Browse productsGET /products
Get a productGET /products/{product_id}
Browse products in a categoryGET /categories/{category_id}/products
Get all categoriesGET /categories
View current user's cartGET /carts/current
Add item to cartPOST /carts/current/items
Update quantity of an item in cartPATCH /carts/current/items/{item_id}
Remove item from cartDELETE /carts/current/items/{item_id}
Place an order from current cartPOST /orders
Get user's ordersGET /users/{user_id}/orders

Note a special case: carts/current. That is a resource that represents "the current user's cart," which is a bit more conceptual but still a resource. We will talk about such special resources next.

Special Resources and Action-like Endpoints

Sometimes you need to represent operations that are not simple CRUD on a single resource. Examples:

There are different ways to model these.

Conceptual resources

You can model some actions as resources themselves.

Examples:

Even though these feel like "actions," you expose them as resources that you create or delete.

Action subresources

Sometimes people use a subresource that looks like an action.

For example, canceling an order:

Here, cancel behaves like a subresource that represents "the cancel operation for this order." The HTTP method POST is still used. This is common and practical, even if it is not purely "resource oriented."

Other examples:

You should not overuse this pattern, but it is acceptable for important actions that do not fit perfectly into standard CRUD.

Versioning and Endpoint Structure (Preview)

You will learn API versioning in a dedicated chapter, but here is how resources and endpoints often look when versioned.

Common pattern:

The resource names and endpoint structure stay the same, but you prefix them with a version, usually as a first path segment.

Example:

Version 1Version 2
GET /v1/tasksGET /v2/tasks
GET /v1/users/{user_id}/tasksGET /v2/users/{user_id}/tasks

The idea is that clients who use /v1/... are not broken by changes in /v2/....

Checklist for Designing Resources and Endpoints

When designing a new REST API, you can walk through this checklist.

  1. List your domain nouns.
    • What are the main things in your system?
    • Example: users, tasks, projects, comments.
  2. Decide which nouns become resources.
    • Not every internal object must be exposed.
    • Start with the biggest, most important ones.
  3. Name collections with plural nouns.
    • /users, /tasks, /projects
  4. Define collection and single resource endpoints.
    • Collection: GET /tasks, POST /tasks
    • Single: GET /tasks/{task_id}, PATCH /tasks/{task_id}, DELETE /tasks/{task_id}
  5. Identify relationships and nested endpoints.
    • Parent child: GET /projects/{project_id}/tasks, GET /posts/{post_id}/comments
  6. Avoid verbs in paths.
    • Use HTTP methods to express actions.
    • Only use action-like subresources when you really need them: /orders/{id}/cancel.
  7. Keep nesting shallow.
    • Prefer at most one level: /projects/{id}/tasks.
    • Avoid very deep URLs.
  8. Choose consistent naming style.
    • Lowercase, hyphens, plural nouns.

If you follow this checklist, your resources and endpoints will be much easier to understand, both for you and for other developers who use your API.

By now you should be comfortable with the ideas of resources and endpoints, how to identify resources in a domain, and how to map them to clear, consistent URLs. In the following chapters, you will see how HTTP methods, status codes, and other REST concepts build on this foundation.

Views: 8

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro
Visitors: 3156 / 24h
Impressum / Imprint
Datenschutz / Data Policy