Endpoints and Resources in APIs — The Building Blocks

What You'll Learn

• What an endpoint is, precisely
• What a resource is in API terms
• How resources map to URLs and methods
• How a complete API is organized

Why This Matters

"Endpoint" and "resource" are two of the most-used words in API documentation. If you cannot point to an endpoint and say "this is the users endpoint, it supports GET, POST, and DELETE", you will struggle to read any API doc. This lesson makes the vocabulary precise.

Simple Explanation

Resource = a thing the API exposes (a user, a post, an order).
Endpoint = a URL where you can interact with one or more resources.

A single endpoint often supports multiple operations. For example, the /users endpoint supports GET (list users) and POST (create a user).

Real-World Analogy — A Bank

Think of a bank. The bank has different counters: one for deposits, one for withdrawals, one for account opening. Each counter is an endpoint. The things you can do there — deposit money, withdraw money, open an account — are operations. The accounts themselves are resources.

You don't go to the deposit counter to open an account, and you don't go to the account-opening counter to withdraw money. Each endpoint is for a specific set of operations on specific resources.

Resources — The "Things"

A resource is anything the API lets you interact with. Common examples:

Resources are usually nouns (not verbs). You don't have a /getUser resource — you have a /users resource and you GET from it.

Endpoints — The "URLs"

An endpoint is the URL you send a request to. It is the combination of:

• The HTTP method (GET, POST, etc.)
• The URL path (/users/123)

So strictly, "the GET /users endpoint" and "the POST /users endpoint" are two different endpoints, even though they share a URL.

The Two URL Patterns — Collection and Single Resource

Most REST APIs use two URL patterns per resource type:

1. Collection URL — plural noun

GET    /users          → list all users
POST   /users          → create a new user

2. Single-resource URL — plural noun + ID

GET    /users/123      → get user 123
PUT    /users/123      → replace user 123
PATCH  /users/123      → update part of user 123
DELETE /users/123      → delete user 123

A Complete Example — The Users API

Six operations, two URL patterns. This is the standard REST layout for any resource.

Nested Resources

Resources can be nested to express ownership:

GET /users/123/posts           → all posts by user 123
GET /users/123/posts/456       → post 456 by user 123
GET /users/123/posts/456/comments   → comments on post 456 by user 123

Nesting shows relationships but should not go too deep. Two levels (/users/123/posts) is fine; four levels (/users/123/posts/456/comments/789/replies) is hard to read and hard to cache.

How an Entire API Is Organized

A real API has many resource types, each with the two URL patterns above. The whole API lives under a base URL:

Base URL: https://api.example.com/v1

Resources:
  /users, /users/{id}
  /posts, /posts/{id}
  /comments, /comments/{id}
  /orders, /orders/{id}
  /products, /products/{id}

API documentation lists every endpoint, the methods it supports, the parameters, the request body, and example responses.

Common Mistakes

1. Using verbs in URLs. /getUser, /createOrder, /deletePost are all anti-patterns. Use nouns + HTTP methods.
2. Mixing singular and plural. /user for one, /users for many is inconsistent. Use plural everywhere: /users and /users/123.
3. Deep nesting. Past two levels, prefer a flat URL with a query parameter: /comments?post_id=456 instead of /users/123/posts/456/comments.
4. Confusing endpoints with operations. "The users endpoint" usually means two URLs (collection + single) supporting six methods. Be precise when discussing APIs.
5. Forgetting versioning. Always include a version prefix (/v1/) so you can introduce breaking changes later without breaking existing clients.

Practical Exercise (5 minutes)

Design the endpoints for a "library" API with three resource types: books, members, and loans. For each, list the collection URL, single-resource URL, and which methods each supports.

Example answer for books:

• GET /books — list all books
• POST /books — add a new book
• GET /books/{id} — get one book
• PUT /books/{id} — replace a book
• PATCH /books/{id} — update a book
• DELETE /books/{id} — remove a book

Do the same for members and loans.

Mini Challenge

Pick any public API you use (Twitter, GitHub, Stripe, Slack). Find its documentation. List five of its endpoints — the URL, the method, and what each one does. Notice how they all follow the same patterns you just learned.

Key Takeaways