REST API
An architectural style for building APIs using standard HTTP methods (GET, POST, PUT, DELETE). Resources are identified by URLs.
What is REST API?
In short
A REST API is a way to build web APIs where every piece of data is treated as a resource with its own URL, and clients act on those resources using standard HTTP methods: GET to read, POST to create, PUT or PATCH to update, and DELETE to remove. Each request carries everything the server needs to handle it, so the server stores no client session between calls.
What a REST API actually is
REST stands for Representational State Transfer. It is a set of conventions for designing HTTP APIs, described by Roy Fielding in his 2000 PhD dissertation. It is not a protocol or a library you install. It is an agreement about how URLs and HTTP methods should be used so that any client can talk to any server without surprises.
The core idea is the resource. A user, an order, a blog post, a payment are all resources. Each one gets a URL, called a URI. For example, GET /users/42 returns user 42, and DELETE /users/42 deletes that same user. The plural noun in the path (/users) names a collection, and the id picks one item out of it.
What comes back is a representation of the resource, usually JSON today, though XML was common in the early years. The client never touches the server's internal storage directly. It only ever sees and edits these representations, which is where the name Representational State Transfer comes from.
How it works under the hood
A REST call is just an HTTP request. The method (verb) says what to do, the path says which resource, headers carry metadata like Content-Type and Authorization, and the body carries data for writes. The server replies with a status code, response headers, and usually a JSON body.
Status codes carry real meaning and clients are expected to read them: 200 OK for a successful read, 201 Created after a POST that made something new, 204 No Content for a successful delete, 400 for a bad request, 401 when you are not authenticated, 403 when you are not allowed, 404 when the resource does not exist, and 500 when the server broke.
REST is stateless. The server keeps no memory of previous requests, so every call must include its own authentication token and any context it needs. This is what lets you run hundreds of identical API servers behind a load balancer: any server can handle any request because none of them hold session state. Two HTTP methods are also idempotent by design, meaning GET, PUT, and DELETE produce the same end result whether you call them once or five times, which makes safe retries possible.
Good REST APIs lean on HTTP features instead of reinventing them: caching through ETag and Cache-Control headers, content negotiation through the Accept header, and partial reads through query parameters like /users?role=admin&limit=50.
When to use it and the trade-offs
REST is the default choice for public web and mobile APIs because it is simple, readable in a browser address bar, cacheable by ordinary HTTP infrastructure, and understood by every HTTP client and tool. Stripe, GitHub, and Twilio all ship REST APIs because any developer can start using them with curl in minutes.
The main weakness is over-fetching and under-fetching. A mobile screen that needs a user's name plus their last three orders might have to call /users/42, then /users/42/orders, then loop over each order. GraphQL solves that with a single tailored query, which is why Facebook built it. For high-throughput service-to-service traffic, gRPC with binary Protocol Buffers is faster than JSON over REST.
REST also has no built-in contract. Two endpoints can return inconsistent shapes unless the team enforces standards, so most serious APIs publish an OpenAPI (Swagger) specification to document and validate the contract. Despite these limits, REST remains the most widely deployed API style on the public internet.
A concrete example
Imagine a simple to-do app. To list all tasks the client sends GET /tasks and gets back 200 with a JSON array. To create one it sends POST /tasks with a body like a title and a done flag, and the server replies 201 Created plus the new task including its generated id, say /tasks/7.
To mark task 7 complete the client sends PUT /tasks/7 with the full updated object, or PATCH /tasks/7 with just the changed field. To remove it the client sends DELETE /tasks/7 and gets 204 No Content. Notice that the same path, /tasks/7, supports read, update, and delete depending only on the HTTP method.
Every one of those calls is self-contained. The request carries an Authorization header with a bearer token, the server validates it, acts on the resource, and forgets the client the moment it responds. That statelessness is what makes REST APIs straightforward to scale and cache.
Where it is used in production
Stripe
Its payments platform is a REST API where charges, customers, and subscriptions are resources acted on with standard HTTP verbs and JSON.
GitHub
The GitHub REST API exposes repos, issues, and pull requests as resources under api.github.com, used by countless integrations and CI tools.
Twilio
Sending an SMS is a POST to a Messages resource, with delivery status read back via GET, all over plain HTTP.
Amazon S3
The S3 API is REST over HTTP: PUT to upload an object, GET to download it, DELETE to remove it, with buckets and objects addressed by URL.
Frequently asked questions
- What is the difference between REST and HTTP?
- HTTP is the underlying protocol that moves requests and responses across the web. REST is a set of design conventions for using HTTP well, mainly mapping resources to URLs and operations to HTTP methods. Every REST API runs on HTTP, but not every HTTP API follows REST conventions.
- Is REST the same as JSON?
- No. JSON is just the most common format REST APIs use to represent resources. REST itself says nothing about format, and early REST APIs often used XML. You can technically return JSON, XML, or other formats and still be RESTful.
- What does stateless mean in REST?
- It means the server keeps no memory of past requests from a client. Each request must carry everything needed to process it, including its authentication token. This lets you run many interchangeable server instances behind a load balancer, since any one of them can handle any request.
- When should I use GraphQL or gRPC instead of REST?
- Use GraphQL when clients need flexible, tailored queries and you want to avoid over-fetching across many endpoints, common in complex mobile and web frontends. Use gRPC for fast internal service-to-service calls where binary efficiency and strict contracts matter more than browser-readable URLs. REST stays the best default for public, cacheable, broadly compatible APIs.
- What are the main HTTP methods in a REST API?
- GET reads a resource, POST creates a new one, PUT replaces a resource entirely, PATCH updates part of it, and DELETE removes it. GET, PUT, and DELETE are idempotent, meaning repeating the same call leaves the system in the same final state.
Learn REST API hands-on
This page explains the idea. The full lesson lets you step through the ring as servers join and leave, read the implementation, and check yourself with a quiz. It is one of 760+ lessons in the System Design Masterclass, from your first API call to distributed consensus. Eleven Foundation lessons are free, no signup. Lifetime access is ₹499 in India or $7.99 worldwide, one payment, no subscription.
See also
Related glossary terms you might want to look up next.
HTTP
The protocol powering the web. A request-response model where clients ask for resources and servers respond. Stateless by design.
GraphQL
A query language for APIs where the client specifies exactly what data it needs. No over-fetching, no under-fetching. One endpoint to rule them all.
gRPC
A high-performance RPC framework by Google using Protocol Buffers and HTTP/2. Much faster than REST for service-to-service communication.
API Gateway
A single entry point for all client requests that routes them to the appropriate microservice. Handles auth, rate limiting, and request transformation.
Latency
The time delay between sending a request and getting a response. Amazon found every 100ms of extra latency costs 1% in sales.
Throughput
The number of operations a system can handle per unit of time. Think of it as how many cars a highway can move per hour.