A REST API is a web service designed around the principles of Representational State Transfer, an architectural style where data is organized into resources, each addressable by a stable URL, and manipulated using standard HTTP methods like GET, POST, PUT, and DELETE. A resource might be a user, an order, or a product, and the API exposes it at a predictable address like `/users/42`, returning a representation of that resource, usually JSON, that a client can read or modify. REST was defined by Roy Fielding in his year 2000 doctoral dissertation, not invented by any single company, and it became the dominant style for web APIs largely because it maps naturally onto HTTP, the protocol the web already runs on. Fielding was one of the authors of the HTTP specification itself, and his dissertation was less about inventing something new than about naming and formalizing patterns that were already emerging in well-designed web systems.
The reason REST APIs exist is that before this style became common, integrating with a remote system usually meant custom protocols, heavyweight standards like SOAP with verbose XML envelopes, or ad hoc conventions that varied wildly from one API to the next. Every new integration required learning a new set of rules. REST exists to give API design a shared, predictable shape: resources at URLs, standard verbs for standard operations, and standard status codes for standard outcomes. A developer who understands GET, POST, and a 404 status code already understands the basic shape of most REST APIs, even ones they've never used before. This shared vocabulary is a large part of why REST spread so quickly: it let two teams that had never spoken to each other build compatible expectations about how an integration would behave, without needing a shared specification document to get there.
The mechanism is built on treating HTTP as more than just a transport pipe: it uses HTTP methods to express intent (GET to read, POST to create, PUT or PATCH to update, DELETE to remove), HTTP status codes to express outcome (200 for success, 201 for created, 404 for not found, 500 for server error), and resource-oriented URLs to express structure (`/orders/17/items` for the items on order 17). What distinguishes a well-designed REST API from a poorly designed one isn't whether it uses these conventions at all, almost everything calling itself REST does, it's how consistently and correctly it applies them, and how much of the interaction's meaning is carried by HTTP itself rather than buried in ad hoc response fields.
By 2026, REST is the default assumption for most web and mobile backend APIs, and it remains the most common choice even as alternatives like GraphQL and gRPC have carved out real space for specific use cases. Its dominance holds because most APIs, most of the time, have simple enough data-fetching needs that REST's straightforward mapping of resources to URLs is easier to build, document, cache, and debug than any alternative. Every major cloud provider, payment processor, and SaaS platform exposes REST APIs as a baseline, and REST familiarity is close to table stakes for any backend or integration engineer. Even organizations that have adopted GraphQL or gRPC for parts of their system usually still maintain REST endpoints somewhere in the stack, whether for public-facing integrations, webhook delivery, or simple internal tooling, because the ecosystem of clients, libraries, and engineers who can work with REST without ramp-up time is larger than for any alternative.
This page covers the actual mechanics that make an API REST rather than just "an API that returns JSON," the practical role of status codes and HTTP verbs, how authentication and pagination typically layer on top, where REST fits next to alternatives like GraphQL and RPC-style APIs, and how a team designs a REST API that holds up well as it grows. The idea underneath all of it is that borrowing HTTP's existing, well-understood semantics for your own API design saves everyone, including your future self, from reinventing conventions that already work. Understanding it lets a team build APIs that other developers can pick up quickly without extensive documentation, because so much of the meaning is already encoded in the shape of the request.
The foundational idea in REST is that everything the API exposes is a resource, a noun, not a verb, addressed by a URL. `/orders` represents the collection of orders, `/orders/17` represents one specific order, and `/orders/17/items` represents the items belonging to that order. This nesting mirrors how the data actually relates, and a developer can often guess the URL structure for a new part of the API just by understanding the pattern already established elsewhere in it. This predictability is one of REST's quieter but more valuable properties: it reduces how much a new integrator needs to look up versus infer.
HTTP verbs then express what you want to do with that resource. GET retrieves it without changing anything, which matters because GET requests are expected to be safe to repeat, cache, and prefetch. POST typically creates a new resource inside a collection, like POST to `/orders` creating a new order. PUT replaces a resource entirely with the data provided, while PATCH updates only the specified fields, a distinction that matters more than it sounds like it should, since PUT semantics imply the client is sending the complete resource state, and PATCH implies a partial update. DELETE removes the resource. Getting this verb usage right isn't pedantry, it's what lets HTTP-aware infrastructure, browsers, proxies, monitoring tools, understand what an API call is actually doing without reading custom documentation.
A common and instructive mistake is designing URLs around actions instead of resources, like `/getOrderById` or `/createNewOrder`, which pushes the verb into the URL redundantly alongside the HTTP method and defeats much of REST's point. Once the URL itself says "get," the HTTP GET method carrying the same meaning becomes decorative rather than functional. Resource-oriented design keeps the noun in the URL and the verb in the HTTP method, and that separation is what makes REST APIs composable and predictable across different resources and teams.
Nested resources need judgment too. `/customers/42/orders` makes sense for listing orders belonging to a specific customer, but an individual order usually shouldn't require its parent in every reference, since an order has a stable identity independent of which customer page you happened to navigate from. Good REST design generally supports both `/customers/42/orders/17` for the nested, contextual view and a flatter `/orders/17` for direct access to the resource by its own identity, rather than forcing every access through a deep, brittle URL hierarchy.
This same judgment extends to how deep nesting is allowed to go. A URL like `/customers/42/orders/17/items/3/reviews/9` technically describes a real relationship chain, but by the third or fourth level it usually stops being useful and starts being fragile, since any change higher up the chain, a customer ID changing, an order getting reassigned, breaks every URL built on top of it. Most mature REST APIs cap meaningful nesting at one or two levels and give deeper resources their own flat, directly addressable paths, reserving the nested form only for the specific views where that context genuinely matters to the client.
HTTP status codes are one of REST's most underused assets, and also one of the clearest markers of a well-built API versus a sloppy one. The 2xx range means success: 200 for a general successful response, 201 specifically for a successful creation, 204 for success with no content to return, like a completed DELETE. The 4xx range means the client did something wrong: 400 for a malformed request, 401 for missing or invalid authentication, 403 for authenticated but not authorized, 404 for a resource that doesn't exist, 409 for a conflict like a duplicate resource. The 5xx range means the server failed: 500 for an unhandled error, 503 for a service that's temporarily unavailable.
APIs that return 200 for everything, including failures, with the actual outcome buried in a JSON field like `{"success": false, "error": "not found"}`, throw away a huge amount of value that HTTP already provides for free. Monitoring tools, load balancers, and API gateways can alert on error rates by watching status codes without needing to understand the specific API's response format. An API that flattens everything to 200 makes that kind of infrastructure-level observability much harder, forcing every consumer to parse response bodies just to know if something worked.
The response body itself still matters, obviously, since status codes communicate broad categories, not specifics. A 404 tells a client the resource wasn't found, but a well-designed error body explains what wasn't found and possibly why, with a stable, documented error code a client can programmatically branch on, not just a human-readable sentence that might change wording between releases and break any code trying to match against it. This distinction, a stable machine-readable error code alongside a human-readable message, is what separates error responses that are actually usable in code from ones that only look informative to a human reading them in a browser.
Consistency across the whole API matters more than any single design choice in isolation. If one endpoint returns 404 for a missing resource and another returns 200 with an empty body for the same conceptual situation, every client integrating with the API has to special-case that inconsistency. This kind of inconsistency tends to creep in naturally as different engineers build different endpoints over time without a shared style guide, which is why REST APIs that stay clean as they grow usually have some form of documented convention, even an informal one, that new endpoints are expected to follow.
Most real REST APIs need authentication, and the common approaches are API keys for simple server-to-server access, OAuth 2.0 bearer tokens for delegated user access (like letting a third-party app act on behalf of a user), and session-based cookies for browser-based first-party clients. None of these are part of the core REST architectural style itself, Fielding's original definition doesn't mandate a specific auth scheme, but in practice almost every production REST API layers one of these on top, typically via the standard `Authorization` header, keeping the authentication concern separate from the resource design itself.
Pagination becomes necessary the moment a collection resource like `/orders` can return more items than it's reasonable to send in one response. The two common patterns are offset-based pagination (`?page=2&limit=50`, simple to implement and understand, but prone to skipping or duplicating items if the underlying data changes between requests) and cursor-based pagination (`?after=abc123`, more resistant to that problem, at the cost of being slightly less intuitive for a client to jump to an arbitrary page). Large-scale APIs with frequently changing data, like a feed of recent events, generally favor cursor-based pagination specifically because offset-based pagination's fragility becomes a real, visible bug at scale, not just a theoretical concern.
Filtering, sorting, and field selection typically show up as query parameters on collection endpoints, like `/orders?status=shipped&sort=-created_at&fields=id,total`. These conventions aren't formally part of REST either, but they've become close to universal because they solve a real, recurring need: letting a client narrow down a large collection without the API needing a custom endpoint for every possible filter combination. The tradeoff is that overly flexible filtering can start to resemble a query language bolted awkwardly onto URL parameters, at which point some teams find that GraphQL's structured query approach fits the actual need better than stretching REST conventions further than they comfortably go.
Rate limiting rounds out the practical layers most production REST APIs need, communicated through headers like `X-RateLimit-Remaining` and a 429 status code when a client exceeds its allotment. This protects the backend from being overwhelmed and gives well-behaved clients a way to programmatically back off rather than guessing. Like authentication and pagination, rate limiting isn't mandated by REST's architectural style, but it's a practical necessity for almost any API serving real traffic, and its absence is usually a sign of an API built for a demo rather than production load.
REST fits best when an API's data maps naturally onto discrete resources with fairly stable, well-understood shapes, and when broad HTTP infrastructure compatibility, caching, monitoring by status code, browser testability, matters. Public APIs, most CRUD-heavy backend services, and integrations meant to be picked up quickly by developers who've never seen your specific API before all play to REST's strengths, because so much of a REST API's behavior can be inferred from familiarity with HTTP itself rather than needing to be learned from scratch.
It fits less naturally when a single client needs to assemble data from many different resources in one screen, the scenario that pushed Facebook toward building GraphQL in the first place. A REST API serving that need either forces multiple round trips or grows a sprawl of purpose-built composite endpoints, each one another thing to design, document, and maintain. Teams with real client diversity, multiple apps each wanting a different slice of overlapping data, often find GraphQL's per-request flexibility solves a problem REST solves only by accumulating more and more bespoke endpoints over time.
For internal, high-performance service-to-service communication, gRPC often takes over from REST, since gRPC's binary protocol buffers and strict schema contracts outperform JSON-over-HTTP for high-volume internal traffic, and internal services can more easily agree on shared tooling than a diverse external developer base could. REST's JSON-over-HTTP approach optimizes for broad compatibility and human readability, which matters enormously for a public-facing API and matters much less for two internal services already built by the same engineering org.
Real-time, event-driven scenarios, live notifications, chat, streaming updates, are another place REST's request-response model doesn't fit naturally, since REST has no native concept of the server pushing data to a client without being asked. These needs typically get handled by WebSocket connections or server-sent events layered alongside a REST API, rather than by stretching REST itself to cover a fundamentally different interaction pattern. A pragmatic system often uses REST for the bulk of its request-response data access and reaches for one of these other tools specifically where REST's model doesn't fit, rather than trying to force one style to cover every kind of interaction. This mix-and-match approach is normal in mature production systems and shouldn't be read as a sign the API design is inconsistent; it's usually a sign the team matched each part of the problem to the tool actually built for it.
The first design decision worth getting right is resource modeling: identifying the actual nouns in your domain and how they nest and relate, before writing a single endpoint. APIs that skip this step and grow endpoint by endpoint, driven by whatever a specific feature needed that week, tend to end up with inconsistent, hard-to-predict URL structures a few years in. Spending real time upfront on how resources relate, what belongs nested under what, and what deserves its own top-level collection pays off in an API that stays legible as it grows.
The second is committing to consistent conventions for status codes, error formats, and pagination before the first version ships, and writing them down somewhere every engineer building a new endpoint will actually see. This doesn't need to be an exhaustive style guide, but it needs to cover the recurring decisions: what status code for common outcomes, what shape for error bodies, what pagination style for collections. Without this, consistency erodes gradually and invisibly, one endpoint at a time, until the API feels different depending on which part of it you're using.
The third is building in versioning and deprecation practices from the start rather than treating them as a future problem, since a REST API that gains real usage will eventually need to change its contract in ways that aren't backward compatible. Deciding, early, whether that will happen through URI versioning, header versioning, or another approach, and how deprecated versions get sunset, saves a painful retrofit later when the API already has a large, established consumer base depending on it.
The fourth is documenting the API in a format that's actually usable by consumers, ideally an OpenAPI (formerly Swagger) specification that can generate interactive documentation, client SDKs, and automated testing, rather than a static document that drifts out of sync with the real behavior of the API over time. An OpenAPI spec, kept accurate through automated checks tying it to the actual API behavior, remains useful for years; a hand-written document nobody's obligated to update tends to become actively misleading within a few release cycles. Tying the spec into the build pipeline, so a request or response shape that no longer matches the documented contract fails a test rather than quietly diverging, is what actually keeps documentation trustworthy over time, since relying on developers to remember to update a separate document by hand rarely survives contact with a real deadline.
A REST API is a web service built around Representational State Transfer principles, where data is organized into resources addressed by stable URLs and manipulated using standard HTTP methods like GET, POST, PUT, and DELETE, with HTTP status codes communicating the outcome.
No. Returning JSON is common but not sufficient. A true REST API also organizes data around resource-oriented URLs, uses HTTP methods according to their intended meaning, and relies on HTTP status codes to express results, rather than burying every outcome inside the response body.
PUT implies replacing the entire resource with the data sent in the request, so any field left out is typically treated as removed or reset. PATCH implies a partial update, changing only the fields included in the request and leaving everything else untouched.
Status codes let HTTP-aware infrastructure, like load balancers, monitoring tools, and API gateways, understand outcomes without needing to parse or understand a specific API's custom response format, which makes error rates, retries, and alerting far easier to build and maintain.
Offset-based pagination (`page=2&limit=50`) is simpler to implement and understand but can skip or duplicate items if data changes between requests. Cursor-based pagination is more resistant to that problem and is generally the better choice for large or frequently changing collections.
When multiple different clients need overlapping but distinct slices of the same data, and building a growing set of bespoke REST endpoints to serve each one is becoming unwieldy. For a single client with stable, straightforward data needs, REST usually stays simpler to build and maintain.
No. REST's architectural style doesn't mandate a particular authentication scheme. In practice, most production REST APIs use API keys, OAuth 2.0 bearer tokens, or session cookies, typically passed via the standard Authorization header, layered on top of the resource design.
OpenAPI, formerly known as Swagger, is a specification format for describing a REST API's endpoints, parameters, and responses in a structured, machine-readable way. It's valuable because it can generate interactive documentation, client SDKs, and automated tests, and it stays accurate far more reliably than a hand-written document maintained separately from the API's real behavior.
gRPC uses binary protocol buffers and strict schema contracts that generally outperform JSON-over-HTTP for high-volume service-to-service traffic, and internal teams can more easily standardize on shared tooling than a diverse external developer base could. REST's broader compatibility and human readability matter less for internal traffic than raw performance does.
