REST (Representational State Transfer) is an architectural style for designing APIs on top of HTTP, the protocol of the web. In a REST API, everything is a resource with its own URL, such as /customers/42 or /orders, and clients work with those resources through standard HTTP methods. REST was described by Roy Fielding in his 2000 dissertation and has since become the most common way for web applications, mobile apps and business systems to exchange data.
How does a REST API work?
- Resources and URLs: each entity (a customer, an order, an invoice) has a unique address.
- HTTP methods:
GETreads,POSTcreates,PUTorPATCHupdates, andDELETEremoves a resource. - Representations: data is usually exchanged as JSON, sometimes as XML.
- Status codes: the response tells what happened, such as
200 OK,201 Created,404 Not Foundor429 Too Many Requests. - Stateless: every request contains everything the server needs, including authentication, so servers don't have to remember sessions and can scale easily.
An example
A web shop that wants to know the status of an order sends GET /orders/1001 to the order system's REST API and receives a JSON response with the order lines, status and track and trace code. To create a new order, it sends POST /orders with the order data in the request body, and the API responds with 201 Created and the URL of the new order.
What makes a good REST API?
A good REST API is predictable: consistent resource names, correct use of methods and status codes, and clear error messages. It also needs authentication (API keys or OAuth 2.0), pagination for large lists, versioning so existing clients don't break when the API changes, rate limiting to protect the server, and documentation, usually as an OpenAPI (Swagger) specification from which client code and test tools can be generated. Requests that may be retried, such as payments, should be idempotent, so a retry never creates a duplicate.
REST vs. SOAP and GraphQL
SOAP is an older, XML-based protocol with strict contracts; it is still used by banks, government systems and accounting software. REST is simpler and lighter, which is why most modern APIs use it. GraphQL lets the client specify exactly which fields it needs in one request, which helps for complex front-ends, but brings its own complexity on the server side. For real-time, two-way communication, a WebSocket is the better fit.
Need a REST API built or connected? See our REST API development, custom API development and API integrations.
Frequently Asked Questions about REST
What is the difference between REST and RESTful?
REST is the architectural style; an API that follows its principles is called RESTful. In practice, both terms are used for any HTTP API built around resources and HTTP methods.
Is REST a protocol?
No. REST is a set of architectural principles, not a protocol or standard. REST APIs almost always use HTTP as the protocol.
Does a REST API always use JSON?
No, but JSON is by far the most common format today. REST itself doesn't prescribe a format; XML, CSV or other formats are also possible.
Is REST secure?
A REST API is as secure as its implementation: HTTPS for all traffic, solid authentication and authorisation per resource, input validation, and rate limiting. REST itself doesn't add or remove security.