REST API
Representational State Transfer API
In short
A REST API is a web API that exposes data as resources identified by URLs and lets clients read or change them using standard HTTP methods.
What is a REST API?
A REST API organizes an application's data into resources, such as users, orders, or products, and gives each one its own URL. Clients work with those resources by sending HTTP requests, and the server usually responds with data in JSON format. REST stands for Representational State Transfer, an architectural style described by Roy Fielding in 2000.
The HTTP method tells the server what to do: GET reads a resource, POST creates one, PUT or PATCH updates it, and DELETE removes it. Status codes in the response, such as 200 OK, 201 Created, or 404 Not Found, report the result. Each request is stateless, meaning it carries everything the server needs, such as an authentication token, so the server does not have to remember earlier requests.
Think of a REST API like a library catalog: every book has a fixed shelf address, and a small set of standard actions (look up, add, update, remove) works the same way for every book. This predictability is why REST is the most common style for public web APIs and for communication between a frontend and its backend.
REST is often compared with GraphQL. A REST API has many endpoints that each return a fixed shape of data, while a GraphQL API usually has a single endpoint where the client describes exactly which fields it wants. REST is simpler to cache and reason about, while GraphQL can reduce the number of requests for complex, nested data.
How it works
Each thing has an address
Every resource the API offers, such as a user or an order, has its own URL.
/users/42The method says what to do
The HTTP method says whether to read it, create one, change it or delete it.
GET POST PUT DELETEThe server answers
It sends back the resource, usually as JSON, with a status code that says how it went.
200 OK · 404 Not FoundNothing is remembered
Each request carries all it needs, such as the token. The server keeps no session between requests.
Authorization: Bearer …
Often misunderstood
You might think: Any API that returns JSON over HTTP is a REST API.
In fact: REST is a set of design rules: resources with their own URLs, the standard HTTP methods and status codes, and requests that stand on their own. One endpoint that takes every action in its body is HTTP and JSON, but not REST.
At a glance
Key takeaways
- REST is an architectural style, not a protocol or a formal standard.
- Resources are identified by URLs, such as
/users/42. - HTTP methods (
GET,POST,PUT,PATCH,DELETE) describe the action. - Requests are stateless: each one carries all the information the server needs.
- Responses usually contain JSON and an HTTP status code.
Example
# Read a list of users
curl https://api.example.com/users
# Read one user by ID
curl https://api.example.com/users/42
# Create a new user by sending JSON
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name": "Ada"}'
# Delete a user
curl -X DELETE https://api.example.com/users/42Readers ask
What is the difference between REST and RESTful?
They mean practically the same thing. REST is the architectural style, and an API described as RESTful is one that follows its principles, such as resource URLs, standard HTTP methods, and stateless requests.
What is the difference between a REST API and GraphQL?
A REST API exposes many endpoints that each return a fixed data shape, while GraphQL usually exposes one endpoint where the client asks for exactly the fields it needs. REST is simpler and easier to cache; GraphQL is more flexible for complex, nested data.
What is the difference between PUT and PATCH?
PUT replaces the whole resource with the data you send, while PATCH updates only the fields you include. Many APIs use PATCH for partial updates and PUT for full replacement.
See also
- REST vs GraphQLREST exposes many URLs that each return a fixed shape of data, while GraphQL exposes a single endpoint where the client asks for exactly the fields it needs.
- REST vs gRPCREST exposes resources over HTTP, usually as JSON, while gRPC calls typed remote functions with binary messages over HTTP/2: faster, but harder from browsers.
- REST vs SOAPREST is a lightweight API style on plain HTTP, URLs and usually JSON, while SOAP is a formal protocol that wraps messages in XML under a strict WSDL contract.
- APIBackend & APIs, p. 2An API is a set of rules that lets one piece of software request data or actions from another in a predictable, documented way.
- HTTPWeb Development, p. 23HTTP is the protocol that browsers, apps, and servers use to exchange web pages and data through a simple cycle of requests and responses.
- EndpointBackend & APIs, p. 15An endpoint is a specific URL, combined with an HTTP method, where an API receives requests and returns responses for one particular resource or action.
- JSONBackend & APIs, p. 28JSON is a lightweight, text-based format for storing and exchanging structured data as key-value pairs and lists, readable by both humans and machines.
- GraphQLBackend & APIs, p. 22GraphQL is a query language and runtime for APIs that lets clients request exactly the data they need, often from a single endpoint in a single request.
- PaginationBackend & APIs, p. 37Pagination is the practice of splitting a large set of results into smaller pages, so an API or website returns a manageable number of items per request.
Free · once a week
Software and AI, explained once a week
The week's software and AI news with every term explained, plus a term to learn and a quick quiz. A two-minute read.
See this week's issueAbout this page
Page history
Added "How it works": resources, methods, answers and stateless requests, and what makes an API RESTful.
Changes that altered what this page says. Typo fixes are not listed.
Spotted a mistake or something missing on this page?Suggest an edit
How pages are made