REST API Design: Clean, Predictable HTTP APIs

Why most APIs are annoying to use

You integrate with an API and within ten minutes you're confused. The endpoint to delete a thing is POST /deleteUser. Creating a record returns 200 OK even when validation failed. Listing 50,000 rows dumps all of them in one response. The error body is a raw stack trace. None of this is hard to fix, it's just that nobody decided on the rules up front.

A good HTTP API is predictable: once you've seen three endpoints, you can guess the fourth. That predictability is not an accident, it comes from a small set of conventions that REST gives you for free. This article walks through those conventions: how to name resources, pick verbs and status codes, shape requests and responses, paginate, filter, and report errors, plus when REST is the wrong tool and you should reach for GraphQL or gRPC instead.

The one principle everything follows from

Model your API around resources, the nouns of your system, and let HTTP's verbs and status codes describe what happens to them. The protocol already has the vocabulary; your job is to use it consistently.

Think of a well-organized public library. Every book has a fixed, predictable address: a shelf, a section, a call number. You don't ask the librarian to runBookFetchProcedure, you say "I want the book at this location," and the action (borrow, return, reserve) is a separate, standard gesture. The catalog is the same for every book, so once you understand one, you understand all of them. A REST API is that catalog: stable addresses for things, standard actions on them.

The resource model, in one picture

Before you write a single handler, sketch the resources and how they nest. A collection (/users) holds items, each item has a stable address (/users/{id}), and items can own sub-collections (/users/{id}/orders). That hierarchy is your whole URL design.

Notice what's missing: there are no verbs in the path. /users/{id}/orders describes a thing, "the orders belonging to this user", and the HTTP method decides whether you're reading the list (GET), adding one (POST), and so on. The URL is a noun; the method is the verb.

Designing one endpoint, step by step

1. 1

   Name the resource as a plural noun

   It's a collection of things, so use the plural: /orders, not /order or /getOrders. Plurals read naturally both for the list (/orders) and the item (/orders/123).

2. 2

   Pick the verb from the action

   Reading is GET, creating is POST, full replace is PUT, partial update is PATCH, removal is DELETE. The verb never goes in the URL.

3. 3

   Decide the request shape

   GET carries no body, filters go in the query string. POST/PUT/PATCH take a JSON body with only the fields the client controls (never let them set id, createdAt, or owner).

4. 4

   Choose the success status code

   200 for a successful read or update, 201 Created for a new resource (with a Location header), 204 No Content for a delete with nothing to return.

5. 5

   Define the response shape

   Return the resource (or a list wrapped with pagination metadata). Keep the shape identical to what the matching GET returns, so clients learn it once.

6. 6

   Map the failure modes to codes

   400 for malformed input, 401/403 for auth, 404 for a missing resource, 409 for a conflict, 422 for validation. Each gets the same structured error body.

Verbs and status codes: the lookup table

Most of REST collapses into one table. Memorize this and you've covered ninety percent of the endpoints you'll ever build. The pattern repeats for every resource in your system, that repetition is exactly what makes the API predictable.

Request and response shapes that scale

The hardest part of a list endpoint isn't the happy path, it's everything around the data. A real GET /users needs pagination (don't return 50,000 rows), filtering (let callers narrow results without new endpoints), and a consistent error shape for when things go wrong. Here's a single well-designed endpoint showing all three.

// Request: filters and paging live in the query string, never the path.
//   GET /users?status=active&sort=-createdAt&page=2&limit=20
//
// Response: 200 OK
{
  "data": [
    { "id": "u_8a31", "name": "Mara Voss", "status": "active", "createdAt": "2026-05-02T10:14:00Z" },
    { "id": "u_8a32", "name": "Theo Lund", "status": "active", "createdAt": "2026-05-02T09:51:00Z" }
  ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "totalItems": 4213,
    "totalPages": 211,
    "nextPage": "/users?status=active&sort=-createdAt&page=3&limit=20"
  }
}

Three things to copy here. The actual records live under a data key, never at the top level, that leaves room to add pagination (and later, things like meta) without breaking clients. Filters and sort are query parameters, so you never invent a new endpoint for "active users sorted by date." And the response hands back a ready-made nextPage link so the client doesn't have to build URLs by hand.

Now the failure case. When validation fails, return a status code that says "you" (a 4xx), not "me" (a 5xx), and a structured body the client can actually parse, not a sentence and definitely not a stack trace.

// Response: 422 Unprocessable Entity
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "requestId": "req_b7c2f0",
    "details": [
      { "field": "email", "issue": "must be a valid email address" },
      { "field": "age", "issue": "must be greater than 0" }
    ]
  }
}

A machine-readable code lets clients branch (if (error.code === "validation_failed")), a human message helps the developer debugging it, a requestId ties the failure to your server logs, and per-field details let a frontend highlight the exact inputs that were wrong. Use this shape for every error in the API, from 400 to 503, so callers write their error handling once.

When REST is the wrong tool

REST is the right default for most resource-shaped, public-facing APIs. But two situations push you elsewhere: clients that need wildly different slices of data (a mobile screen wants 3 fields, a dashboard wants 30), and high-throughput internal service-to-service calls where every millisecond and byte counts.

Common mistakes that make APIs painful

1. Verbs in the URL. POST /createUser, GET /getUserById, POST /users/123/delete. The method already is the verb, use POST /users, GET /users/123, DELETE /users/123.
2. Returning 200 for errors. A 200 OK wrapping { "success": false } forces every client to parse the body to know if the call worked, and breaks monitoring that watches status codes. Let the status code tell the truth.
3. No pagination on list endpoints. Returning every row works in dev with 12 records and falls over in prod with 12 million. Paginate from day one, adding it later is a breaking change.
4. Leaking internals. Stack traces, SQL fragments, ORM class names, and internal IDs in responses are a security and coupling hazard. Return a clean structured error with a requestId, and keep the gory details in your logs.
5. Inconsistent shapes. data here, results there, items somewhere else; snake_case in one endpoint, camelCase in another. Pick one convention and enforce it everywhere, consistency is the whole product.

Takeaways

Where to go next

You now have the shape of a clean API. The next questions are how it changes over time and how you keep it safe, both are their own disciplines.

• API Design: Evolution & Versioning, how to change an API without breaking the clients already depending on it.
• Secure API Design, authentication, authorization, rate limiting, and the inputs you must never trust.
• How the Web Works: HTTP Requests, the request/response fundamentals everything here builds on.
• Follow the full Backend Engineer path to see where API design sits in the bigger picture.