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.
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.
Often compared
- 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.
See also
- 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. 19HTTP 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. 12An 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. 25JSON 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. 19GraphQL 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. 34Pagination 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.
Sources
Spotted a mistake or something missing on this page?Suggest an edit