🗺️ API Endpoint Design

Why Endpoint Design Matters

Your endpoints are the public face of your API — the part every consumer touches. Thoughtful design pays off in ways that compound: a smaller learning curve, fewer support tickets, easier documentation, and the freedom to evolve without breaking clients. Sloppy design does the opposite, and once developers have integrated against your URLs, they're expensive to change.

Resource Naming

You met the golden rule last lesson: URLs are nouns, methods are verbs. Endpoint design is about applying that rule consistently across an entire API. Consistency is the real prize — one predictable pattern beats a dozen individually-clever ones.

Nouns, not verbs

Plural collections

Prefer plural nouns for collections — /users, not /user. It reads naturally both for the whole set (/users) and for one member (/users/123), and it's the dominant industry convention. Whatever you choose, be consistent: never mix /users with /product.

Casing and clarity

# A consistent e-commerce resource vocabulary
GET /products
GET /products/123
GET /categories
GET /categories/electronics
GET /customers
GET /customers/456
GET /orders
GET /shopping-carts/abc

URL Hierarchy & Nesting

Resources relate to one another, and your URL structure should reflect those relationships — but only up to a point. The art is knowing when to nest and when to flatten.

Nested resources show ownership

GET  /users/9/posts              # posts BELONGING TO user 9
GET  /users/9/posts/42           # a specific post by user 9
POST /users/9/posts              # create a post for user 9
GET  /posts/42/comments          # comments ON post 42
POST /posts/42/comments          # add a comment to post 42

Nesting communicates "this belongs to that." It also scopes access naturally — /users/9/posts can't accidentally return another user's posts.

Know when to flatten

Nesting is seductive, but every extra level makes URLs longer and clients more brittle. Cap nesting at two, occasionally three, levels. Beyond that, give the deep resource its own top-level home or use query parameters.

# ❌ Too deep — painful to build, painful to read
GET /users/9/posts/42/comments/7/replies/3

# ✅ Flatten: expose the resource directly
GET /replies/3
GET /comments/7/replies

# ✅ Or scope with a query parameter
GET /replies?commentId=7

Path parameters

The :id placeholders in a route are path parameters — they identify which resource. Name them descriptively (:userId, not just :id) and consistently across endpoints. In Express they arrive on req.params:

app.get('/users/:userId/posts/:postId', (req, res) => {
  const { userId, postId } = req.params;   // both path parameters
  const post = getPost(userId, postId);
  if (!post) return res.status(404).json({ error: 'Not Found' });
  res.json(post);
});

Filtering, Sorting & Pagination

Path segments identify which resource; query parameters modify how a collection is returned. They never change the resource itself — they filter, order, page, and trim it. This is exactly where query strings belong (and where they shine).

Filtering

GET /products?category=electronics          # one filter
GET /products?category=electronics&inStock=true   # combine filters
GET /products?price_gte=100&price_lte=500   # a range with operator suffixes
GET /articles?title_contains=javascript     # partial match

Sorting

GET /products?sort=price          # ascending by default
GET /products?sort=-price         # leading "-" means descending
GET /users?sort=lastName,firstName  # multiple keys, in order

Pagination

Always paginate collections — an unbounded list is a performance incident waiting to happen. Two common styles:

Field selection

GET /users?fields=id,name,email    # return only these fields (lighter payloads)

Here's a collection handler in Express that filters, sorts, and paginates — and, crucially, returns pagination metadata so the client knows how to navigate:

app.get('/api/products', (req, res) => {
  const {
    category,
    sort = 'name',
    page = 1,
    limit = 20
  } = req.query;

  let results = [...products];

  // 1. Filter
  if (category) {
    results = results.filter(p => p.category === category);
  }

  // 2. Sort ("-price" = descending, "price" = ascending)
  const desc = sort.startsWith('-');
  const key = desc ? sort.slice(1) : sort;
  results.sort((a, b) => (a[key] > b[key] ? 1 : -1) * (desc ? -1 : 1));

  // 3. Paginate
  const pageNum = parseInt(page, 10);
  const perPage = Math.min(parseInt(limit, 10), 100);   // cap page size!
  const total = results.length;
  const start = (pageNum - 1) * perPage;
  const pageItems = results.slice(start, start + perPage);

  // 4. Respond WITH metadata
  res.json({
    data: pageItems,
    pagination: {
      total,
      page: pageNum,
      perPage,
      totalPages: Math.ceil(total / perPage),
      hasNext: start + perPage < total,
      hasPrev: pageNum > 1
    }
  });
});

{
  "data": [ { "id": 1, "name": "Keyboard", "category": "electronics" } ],
  "pagination": {
    "total": 243,
    "page": 2,
    "perPage": 20,
    "totalPages": 13,
    "hasNext": true,
    "hasPrev": true
  }
}

Action Endpoints

Most operations map cleanly to CRUD, but some don't. "Cancel this order," "publish this post," "send a password reset" — these are operations or state transitions, not resource creations. REST has a pragmatic escape hatch for them.

First, try modeling as state

Before inventing an action endpoint, ask whether it's really just a field change. Publishing a post might simply be a PATCH:

PATCH /posts/42
{ "status": "published" }

When an action is clearer, POST to a sub-resource

If the operation has side effects beyond a simple field (charging a card, sending mail, running a workflow), a named action reads better. Use POST to a verb sub-path on the specific resource:

POST /orders/123/cancel          # cancel order 123
POST /orders/123/refund          # refund order 123
POST /users/9/verify-email       # trigger email verification
POST /carts/abc/checkout         # run the checkout workflow

Controller resources for cross-cutting operations

A few operations don't belong to any single resource — a global search, a shipping-cost calculation. Model these as standalone "controller" resources, used sparingly:

POST /search                     # complex search with a request body
POST /calculate-shipping         # compute a quote from address + weight

Versioning

APIs evolve, but existing clients don't upgrade on your schedule. Versioning lets you ship breaking changes without breaking anyone. The cardinal rule: introduce a new version for breaking changes; never break an existing one.

Path versioning is a natural fit for Express routers — mount a whole version under a prefix:

const express = require('express');
const app = express();

// Each version is its own router module
const usersV1 = require('./routes/v1/users');
const usersV2 = require('./routes/v2/users');

app.use('/api/v1/users', usersV1);
app.use('/api/v2/users', usersV2);   // breaking changes live here

// v1 clients keep working untouched while v2 evolves independently

Practice & Quiz

# Posts (CRUD)
GET    /api/v1/posts
POST   /api/v1/posts
GET    /api/v1/posts/:postId
PUT    /api/v1/posts/:postId
PATCH  /api/v1/posts/:postId
DELETE /api/v1/posts/:postId

# Nesting: a user's posts, a post's comments
GET    /api/v1/users/:userId/posts
GET    /api/v1/posts/:postId/comments
POST   /api/v1/posts/:postId/comments

# Flat access to one comment
GET    /api/v1/comments/:commentId
PATCH  /api/v1/comments/:commentId
DELETE /api/v1/comments/:commentId

# Action + filtering
POST   /api/v1/posts/:postId/publish
GET    /api/v1/posts?author=9&status=published&sort=-createdAt&page=1&limit=10

app.get('/api/tasks', (req, res) => {
  let results = [...tasks];
  const { sort = 'createdAt' } = req.query;
  // TODO: apply ascending/descending sort based on a leading "-"
  res.json({ data: results });
});

app.get('/api/tasks', (req, res) => {
  let results = [...tasks];
  const { sort = 'createdAt' } = req.query;

  const desc = sort.startsWith('-');
  const key = desc ? sort.slice(1) : sort;

  results.sort((a, b) => {
    if (a[key] === b[key]) return 0;
    const order = a[key] > b[key] ? 1 : -1;
    return desc ? -order : order;
  });

  res.json({ data: results });
});

Best Practices & Pitfalls

✅ Do

• Be consistent above all — one naming and structure pattern across the whole API
• Use plural nouns and keep URLs readable and self-descriptive
• Put filtering, sorting, and paging in query parameters
• Always paginate collections and cap the maximum page size
• Version from v1 and reserve new versions for breaking changes

❌ Don't

• Nest resources more than 2–3 levels deep
• Put verbs in paths, except sanctioned action sub-resources (/orders/123/cancel)
• Return an unbounded collection with no pagination
• Mix singular and plural, or kebab-case and camelCase, across endpoints
• Bury filtering criteria in the URL path (/users/active/admins)

# ❌ Every filter combination becomes a new route to build and document
GET /users/active/admins/sorted-by-name

# ✅ One route, infinite combinations, all in query parameters
GET /users?status=active&role=admin&sort=name

Summary

📚 Additional Resources

• restfulapi.net — REST Resource Naming Guide
• MDN — The URL interface
• Express — Routing guide
• Martin Fowler — Richardson Maturity Model

🚀 What's Next?

You've designed the shape of an API; next you'll master the payloads that flow through it. The following lesson, Handling JSON Data, covers parsing request bodies, structuring JSON responses, validation, and the middleware that ties it together in Express.