A practical guide to REST API design

| REST API

This is an article about REST API design principles. This is a practical, opinionated guide. I have explained so many times how to design REST API so I decided to put them in writing and save the future myself the hassle. The article is framework-agnostic and discusses API shape design, not implementation details.

This topic is already covered extensively: there are not one, but two books with animals on their covers (which was a sign of quality back then): RESTful Web APIs and REST API Design Rulebook, in addition to surprisingly solid, albeit slightly unfinished Your API is bad that I usually recommend. There is also the obligatory Wikipedia entry, that is, at the time of writing (end of '26), is more about the history of the term rather than practical usage.

Today, many developers are as clueless about REST API principles as before, and oftentimes have no idea what REST abbreviation stands for. In a way, REST for some became a generic term for any HTTP API, just like every copy machine is Xerox now. You can't really tell your team to "go read that book" anymore, because who even reads books in 2026? Fortunately, you still can get away with "go read that article".

This is the article.

REST API building blocks

First of all, REST = "Representational State Transfer". We'll get to what it means in a moment. What is important is that not every HTTP API is RESTful. An API can be built on a different foundation, such as GraphQL, gRPC (which is fine), or don't follow any principles at all and grow organically (which is bad).

Modern RESTful APIs are mainly built around four concepts:

  • Resources
  • Collections that hold resources
  • Actions on resources and collections
  • Views (aka Representations) of resources and collections

What is a resource? What is a collection?

A resource is a business entity in your app. A user account, an order, an item in an e-commerce store, a Forex deal - all of these are resources. Each resource has a unique ID that identifies the resource unambiguously. The shape of this ID is not that important, as long as it does its job. It could be a simple running number (1, 2, 3), a GUID, a string, a hash - anything works, as long as it's unique within its collection.

Resources of the same type form collections. In REST APIs, collections and resources are usually mapped to URLs like this:

<collection name>/<resource ID>.

Examples:

  • /clients/123 - identifies a resource with ID 123 in the collection "clients".
  • /orders/00eb29fb-c1e6-421b-acda-0eef5a95547e - this one uses GUID to identify the resource.
  • /managers/john-doe totally fine too, as long as "john-doe" is guaranteed to be unique in this collection.

Collection names are usually plural ("users", not "user").

Collections and resources can be nested:

  • /clients/123/orders is a path to the collection of orders of the client 123.
  • /clients/123/orders/456 is a path to the order 456 of the client 123.

Actions

If we look closer at resources and collections, we'll see that there are not too many things we can do with them. We can:

  1. Add new resources to collections;
  2. List collection items. Maybe sorted or filtered by some criteria;
  3. Update a resource, fully or partially;
  4. Delete one or many resources from a collection.

These four actions - Create, Read, Update, Delete, or CRUD, constitute 90% of business logic of all apps in the world. Registration of a new user? That's a Create. Change client's email or reset password? That's an Update. Pay for an order on an e-commerce website? That's probably a bunch of Creates and Updates (create an order, create a payment record, update the inventory). Get first 10 items in the "vacuum cleaners" category, filtered by price and tags? That's a Read. There are exceptions, but vast majority of actions in a typical API fit the CRUD paradigm nicely. Some do not, we'll discuss them later in the article.

In modern REST, actions are mapped to requests using HTTP verbs:

  • POST requests are used to create resources;
  • GET - to read them;
  • PUT for full resource replacement;
  • PATCH - for partial update;
  • DELETE for, well, deletion.

Additionally, server response codes are used to communicate action results to a caller. We'll get to them later in this guide.

Practical examples of building RESTful URLs

Almost any app has some concept of users, so we'll take a users collection as an example, with single user as a resource. We'll also use JSON format for payloads, for simplicity.

Creating resources

Creating a new resource (a user in our case) would be a POST HTTP request to /users, with the payload passed as a request body:

POST /users

{
    "name": "John",
    "lastName": "Doe",
    "role": "customer"
}

We're basically saying: "create a new entry in the Users collection". Once a resource is created, it is typical in REST to return it in a response. So, creating a new User could return an HTTP response with a status 201 Created and a body like this:

{
    "id": 123,
    "name": "John",
    "lastName": "Doe",
    "role": "customer",
    "createdAt": "2026-10-12T10:00:00"
}

This JSON response is not a user object itself - it's a representation of its current state, that was just transferred (remember, REST stands for Representational State Transfer).

Note that once a resource is created successfully, it is assigned an ID that can be used to work with this resource later. For example, we can fetch this user's current state by sending a GET request to /users/123. It should return a payload in the same shape as in the previous example.

In some cases it's OK to return just the ID of a newly created resource and omit other details. Usually it's a performance tradeoff.

Sometimes API accepts a resource creation request but doesn't execute it immediately, and handles it in background. In this case, a response should be a 202 Accepted status code with no body.

Fetching data from server

To get a single resource, we usually reference it by ID: GET /users/123.

To list resources of a collection, we typically use GET request on that collection: GET /users. In case of a JSON response, we would get an array of objects:

[
    {
        "id": 123,
        "name": "John",
        "lastName": "Doe",
        "role": "customer",
        "createdAt": "2026-10-12T10:00:00"
    }, {
        "id": 124,
        "name": "Jane",
        "lastName": "Doe",
        "role": "customer",
        "createdAt": "2026-11-12T10:05:00"
    }, {
        "id": 125,
        "name": "Jack",
        "lastName": "Smith",
        "role": "lead",
        "createdAt": "2026-11-12T10:05:00"
    }
]

Sometimes it's necessary to get just a part of a resource. Usually when the resource is heavy and fetching it whole would be wasteful. In this case, it's OK to use the part name after the resource ID:

GET /users/123/email

GET /orders/456/status

As an additional bonus, it allows for more granular permissions management.

Filtering

Oftentimes a response needs to provide filtered and/or sorted information, not just a list of all entries. Filtering goes to query string:

GET /users?name=Jane

If there are multiple filters, every of them gets a separate query parameter:

GET /users?name=John&role=customer

— How to search for multiple values of the same parameter? Say, I need users whose role is either Customer or Lead.

There are several options. None of them is a part of HTTP standard, so it's mostly a matter of personal taste.

Option 1: repeat the name several times

GET /users?role=lead&role=customer

Often seen in the wild, but be careful - some server frameworks might silently overwrite repeated names, so the backend would see only the first or the last value.

Option 2: use array-like indexing in URLs

GET /users?role[0]=lead&role[1]=customer

Note that brackets symbols [ and ] must be URL encoded to work properly!

Option 2 is my go-to recommendation, since it makes the intent clear and non-accidental.

Option 3: just use a comma

GET /users?role=lead,customer

Simple, but not always convenient, especially if the search value itself has commas. Theoretically, another separator can be used:

GET /users?role=lead|customer

It can work, but "|" requires URL encoding, since it's not a whitelisted special symbol. Generally there are no reasons to use it over comma.

Sorting

Sorting works in a similar fashion - pass sorting parameters in a query string:

GET /users?sortBy=createdAt&sortDir=desc

If there are multiple sorting fields, use the same array-like indexing as in filtering:

GET /users?sortBy[0]=createdAt&sortDir[0]=desc&sortBy[1]=id&sortDir[1]=asc

A shorter option is to combine sortBy and sortDir:

GET /users?sortBy[0]=createdAt:desc&sortBy[1]=id:asc

It looks a bit cleaner, but is slightly more difficult to build and parse. Mostly a matter of taste.

Pagination and limiting

Usually API endpoints should have some sort of pagination and response chunking. Imagine having a million users in your database. A naive GET /users would try to fetch them all at once, putting serious load on the application or even outright crashing it. To avoid this, endpoints usually have some reasonable limit of results that can be fetched in a single batch. If an API has a limit of, say, 100 results per request and the collection has 250 records total, a client should perform 3 consecutive requests to fetch them all: 100 + 100 + 50.

There are two approaches to pagination in URLs:

  1. Use page number: GET /users?page=1

This is the simplest approach, but an inflexible one. Page size is defined on the server side.

  1. (better) Use offset and limit.

GET /users?offset=25&limit=5 means "skip the first 25 users and give me the next five".

This is what is usually seen in production. The parameter names can be different (e.g. "skip/take" or "start/length" instead of "offset/limit"), but the principle is the same. If omitted in a request, offset and limit should be set to default values on the server side.

  1. Cursor-based pagination. It uses a cursor that points to a position in the result set, rather than a page number or an offset.

Example: GET /users?limit=5. Response:

{
  "data": [
    { "id": 101, "name": "Alice" },
    { "id": 102, "name": "Bob" },
    { "id": 103, "name": "Charlie" },
    { "id": 104, "name": "David" },
    { "id": 105, "name": "Eve" }
  ],
  "nextCursor": "eyJsYXN0SWQiOjEwNX0="
}

The client uses the returned cursor to request the next batch: GET /users?limit=5&cursor=eyJsYXN0SWQiOjEwNX0=. The server decodes or looks up the cursor, determines where to continue, and returns the next five users. The cursor might encode the last user's ID, a timestamp, a combination of sorting fields, or an opaque token that the server interprets. This approach is often used with feed-based, "infinite scroll" apps such as social networks, where content is added often and has transient nature.

For most apps out there, option 2 is a preferable choice. A full example with filtering, sorting and pagination:

GET /users?role=lead&sortBy=id&sortDir=desc&offset=10&limit=10

Advanced filtering: negation, ranges, non-strict equality

The previous examples cover most of the everyday filtering and sorting situations. But sometimes you need to use advanced filtering logic in the URL. For example, how to filter for all users whose last name is not "Doe"? How to get all users registered between 10/10/2026 and 12/10/2026?

Let's take another look at one of the previous examples: GET /users?lastName=Smith. Its query string consists of three parts: "lastName" is a parameter name, "=" is an operator, and "Smith" is a value. The equality operator (=) comes for free - every backend framework knows how to work with it. Unfortunately, other comparison operators are not. Consider the following examples:

  • /users?lastName!=Smith
  • /users?registeredAt>2026-10-10T00:00:00Z
  • /users?id like 123

They're not technically illegal, in a sense that they can be passed in a request (when properly URLencoded), they won't be recognized by the backend "for free". Such operators require custom parsing and special treatment on the backend side.

There are several common ways to structure such operators. Let's define a searchParam data structure in pseudo-code:

struct SearchParam {
    key: string;
    op: "equal" | "non-equal" | "like" | "greater-than" | "lesser-than";
    value: string;
}

Note the op[erator] member. Using this structure, we can describe non-trivial filters in our URLs:

  • GET /users?key[0]=lastName&op[0]=non-equal&value[0]=Smith - any last name except Smith;
  • GET /users?key[0]=firstName&op[0]=like&val[0]=smith - all first names like "smith": Smith, Smithson, Goldsmith etc;
  • GET /users?key[0]=deletedAt&op[0]=greater-than&val[0]=2026-10-12T00:00:00Z&key[1]=deletedAt&op[1]=lesser-than&val[1]=2026-12-12T00:00:00Z - deletedAt date in an interval

A bit verbose, but still readable and very flexible.

Another option is to embed operators with field names, like this:

  • GET /users?lastName_noneq=Smith
  • GET /users?firstName_like=smith
  • GET /users?deletedAt_greaterthan=2026-10-12T00:00:00Z

A matter of taste. I personally find it a bit more clumsy.

Not every endpoint needs this complex search criteria, but sometimes there is no other way around.

Empty collections

Empty collections should return an empty array and 200 OK HTTP response. Don't return 404 error or null. A collection, even if empty, still exists.

Modifying resources, fully or partially

Use PUT request to replace a resource completely. PUT = "replace the resource at the given ID with the payload I'm sending".

PUT /users/123

{
    "name": "John",
    "lastName": "Smith",
    "role": "customer",
    "createdAt": "1970-01-01T00:00:00"
}

Note that resource ID is immutable and can't be updated. PUT requests usually return either 200 OK with no body, or, rarely, the whole resource, just like POST. Usually it's not necessary, because the sender already knows the desired resource shape and needs just a confirmation that their changes applied successfully.

"Replace resource completely" in this context can mean "almost completely", or even "not quite completely", if your app business rules demand it. E.g., user's email or phone number update sometimes are separate operations, because they require ownership confirmation.

Use PATCH to update just one resource property. The URL format stays the same:

<collection>/<resource ID>

For example, to update user role, we'd send this request:

PATCH /users/123

{
    "role": "lead"
}

It doesn't have to be only one field. PUT vs PATCH difference is not about the number of fields, it's about the general intention: do we want to update a resource partially, or replace it completely?

Deleting resources

Deletion is trivial, you just send a DELETE request with the resource ID:

DELETE /users/123

Note that you usually delete resources, but not collections. A collection, even if empty, is still an existing entity. An app with zero users still has the users/ collection.

Calling DELETE on a collection is sometimes interpreted as deletion of all collection resources. In practice, it's rarely needed.

Some applications have a so-called "soft deletion", when a resource is not actually wiped. It's just marked as "deleted", but actually stays in the database. Such operations should still be treated as deletions, not partial updates (DELETE, not PATCH), because the API represents business intent, not implementation details.

Actions that don't map to CRUD nicely

As I said before, most actions map to REST API naturally, with some notable exceptions.

Bulk operations

What if we need to create, update or delete resources in bulk?

Bulk creation is straightforward - we just send an array of objects instead of a single object in our POST:

POST /users

[
    {
        "name": "John",
        "lastName": "Doe",
        "role": "customer"
    }, {
        "name": "Jane",
        "lastName": "Smith",
        "role": "customer"
    } 
]

The response here is either an array of newly created IDs, or rarely, an array of created objects.

For bulk update, the cleanest option is to send PATCH on collection:

PATCH /users

{
    "ids": [1, 2, 3],
    "role": "lead"
}

As with normal PUTs or PATCHs, a 200 OK with no body is a typical response.

Mass deletion is a bit more tricky, because DELETE requests don't have a body. So this approach is wrong:

DELETE /users

{
    "ids": [1, 2, 3]
}

Passing IDs for deletion in a query string is also not a good idea. Query strings are for querying, deletion is not querying. While it technically can be done, it breaks the REST semantic and has its pitfalls. For example, query strings have a length limit. The limit is not a part of HTTP standard, but it exists and varies between implementations.

There is really no universally accepted, clean solution for this problem. Every approach is a compromise. One option is to introduce a pseudo-collection /users-bulk-operations and POST to it something like this:

{
    "ids": [1, 2, 3],
    "action": "delete"
}

Login, logout, registration

Many APIs have /login and /register endpoints. Both "login" and "register" are neither a resource nor a collection, but this usage is so ubiquitous that you might just roll with it.

A cleaner option is to use POST to users/ to register a user. Registration is a user creation.

login is bit tricky. A good mental model here is that when a user logs in, they start an authenticated session. A session is a resource, and sessions is a collection, so we can POST to sessions for a login. Furthermore, GET users/<id>/sessions can be used to see all active user sessions on all devices, DELETE users/<id>/sessions/<session-id> to log the user out of one session, and DELETE /users/<id>/sessions to end all user sessions. Very clean and RESTful.

Impersonation

Also known as "logging in from admin on behalf of a user". Usually there is some kind of Admin or CRM app where admins can see clients' information. If the system has poorly designed security, admins can just see clients' usernames and passwords and copy them. More secure system store passwords as hashed strings and never show them as plain text. To login on behalf of a user, admin needs to call a designated endpoint that returns a cookie or JWT. Similar with normal logins, a successful request starts an authenticated session, so it's going to be a POST to /sessions. The neat part is that the admin themselves needs to be logged in to impersonate a user. The endpoint would work in two different modes:

  1. A normal login. POST to /sessions with username and password:
{
    "username": "joe@example.com",
    "password": "test 123"
}
  1. Impersonation. Again, POST to the same endpoint, but without a password (since admin doesn't know it), but with the admin's authorization cookie or token.

Headers:
...
Authorization: Bearer {token}

Body:

{
    "username": "joe@example.com"
}

Authentication and authorization

While we're here, let's talk about authentication a bit.

An API endpoint can be either public (available for everyone) or private (available only to authorized users). Some endpoints must always accept anonymous request by design, for example aforementioned registration and login endpoints. Others are open only for authorized requests. In rare cases, like with the impersonation, an endpoint may accept both anonymous and authenticated requests and process them differently.

Authentication or authorization?

These concepts are not interchangeable. "Unauthenticated" means "we don't know you are". In HTTP that's response code 401. "Unauthorized" means "we know who you are, but this action is forbidden for you". In HTTP, that's code 403. A user can be authenticated (so we know him), but not authorized (e.g., a client trying to perform an action that is allowed only for admins).

Historically though, the official 401 response name in HTTP is "Unauthorized", which is...not exactly wrong, but semantically misleading and leads to constant misunderstanding.

A login request exchanges a set of credentials (usually username + password) to a cookie or JWT. Subsequent requests then carry the cookie or the token on them. HTTP is a stateless protocol, so usually the cookie or the token should be sent with every request.

There are rare exceptions. Notably, MetaTrader HTTP API works differently. After a successful login, it just keeps a TCP connection alive using keep-alive header and treats all request arriving through this connection as authenticated. This is a highly unusual setup and it generally should be avoided, until you have a serious technical reason not to.

Views, representations

A resource or a collection may have multiple views, or representations. An example: application admin sends a GET /users and sees full information about all users, but a sales manager that sends the same request would see just a small subset of it. Another example: a user resource is very large and includes dozens of fields: address, purchase history, login history, tags, groups etc. GET /users/<id> returns full information about them, but when calling GET /users, each user view is just a bunch of minimally necessary fields (id, name, email). The idea is that a resource or a collection may have multiple representations that are defined by concrete business logic.

In some cases, a view is implicit and defined by the endpoint itself. In the second example, GET /users would always return a "short" view, while GET /users/<id> would always return a "full" view. In other cases, a required view can be a part of the request itself: GET /users?view=full.

In addition to choosing the payload shape, we sometimes need to choose its media type. E.g.: GET /users might be used to get a JSON-formatted response to display in a browser, or a downloadable PDF file to export. In HTTP, "Content-Type" header is responsible for that, and it's a good tone to use it. Technically, nobody prevents you from sending in in a query string or a body: GET /users?format=pdf, but better to avoid that.

HTTP response codes

At the bare minimum, just three response codes are enough:

  • 200 OK - operation completed normally;
  • 400 Bad Request - something went wrong, and the client is to blame (e.g., a client provided invalid data);
  • 500 Server Error - something went wrong, and the server is to blame (e.g., a database is down, the API is overloaded - any situation when the client's request can't be processed, but this is not the client's fault);

A lot of public APIs stick to these three.

A more detailed version:

Operation URL Response code Response body
New resource POST /collection 201 Created Full new resource, or just ID
Resource replacement PUT /collection/resource-id 200 OK or 204 No Content Usually no body, rarely - replaced resource
Partial resource update PATCH /collection/resource-id 200 OK or 204 No Content Usually no body, rarely - updated resource
Resource deletion DELETE /collection/resource-id 200 OK or 204 No Content No body
Bulk operation in background Varies 202 Accepted No body

How to handle bulk operations with mixed results?

Sometimes an operation succeeds only partially. E.g.: we want to delete 10 users, but only 8 were actually deleted. The response here should be 200 OK, with the body containing per-item information, either an OK mark or a failure reason. Don't use `207 multi-status` response code for such cases. It exists and is sometimes seen in the wild, but its intended use is WebDAV, not HTTP APIs.

Don't return 2xx code if something went wrong. 200 OK and an error description in the body is a bad practice. Also, don't document 5xx as expected error in your API docs. It is always unexpected and ideally should never happen.

Same operation, different endpoints

API endpoints sometimes have duplicated functionality. GET /orders?userId=123 and GET /users/123/orders look different but could, in fact, go to the same API controller. That's totally OK, as long as it makes sense in the context of your app's business logic.

Notable mention: HATEOAS

Hate...oats?

"Hypermedia as the engine of application state". Another abbreviation, less known than REST, but related to it. In short, it's when you add a bunch of navigation links to your API responses, like this:

GET /users/123

{
    "id": 123,
    "name": "John",
    "lastName": "Doe",
    "role": "customer",
    "createdAt": "2026-10-12T10:00:00",
    "links": {
        "self": "https://example.com/users/123",
        "orders": "https://example.com/users/123/orders",
        "sessions": "https://example.com/users/123/sessions"
    }
}

A neat idea in theory, but in practice it adds a payload to every response, and this payload is a dead weight in 90% cases. You probably don't need that. A better way to improve discoverability is to provide good, up-to-date, well-formatted documentation.

A word on API documentation

Documentation should live in the code. In .NET (and many others) use Swagger annotations. They should be visible on code review. Tested time and time again: documentation not near the code = desync, stale information. Every corporate wiki inevitable turns into a graveyard. Docs in the code tend to stay relevant.

Conclusion

REST is not a formally defined standard, it's a set of principles. A lot of opinions in this guide are just opinions, not facts set in stone. Still, if you follow this advice you'll have a sane and consistent API that you can confidently send to your clients and 3rd-parties.

It's impossible to compress a content of a book in a single article, even a lengthy one, so some topics are barely touched or omitted altogether. If you need a deeper dive, go read that book.

Your team still struggles to build a good API even after reading this guide? Call me and I'll deal with them personally.