REST follows a client-server architecture. The server is in charge of handling a set of services, listening for requests made by clients. The communication between client and server must be stateless, meaning that server do not store any record from the clients and therefore each request done from the client must contain all the information required for the server to process it separately.
The building blocks of REST architectures are named resources. Resources define the type of information that is going to be transferred. Resources should be identified in a unique way. In HTTP, the way to access the resource it to provide its full URL, also known as API endpoint. Each resource has a representation, which is a machine-readable explanation of the current state of a resource. Nowadays, representations are usually with JSON, but it can be done in other formats such as XML or YAML.
Once we identified the resources and the representation format, we need to specify what can be done with them, that is, the actions. Actions could potentially be anything, although there is a set of common actions that any resource-oriented system should provide: CRUD (create, retrieve, update, and delete) actions. REST actions can be mapped to the HTTP methods (so-called verbs), as follows:
- GET: Reads a resource.
- POST: Sends a new resource to the server.
- PUT: Updates a given resource.
- DELETE: Deletes a resource.
- PATCH: update partially a resource.
- HEAD: Asks if a given resource exists without returning any of its representations.
- OPTIONS: Retrieves a list of available verbs on a given resource.
In REST, it is important the notion of idempotency. For example, GET, DELETE, or PUT are said to be idempotent, since the effect of these requests should be the same whether the command is sent one or several times. On the other hand, POST is not idempotent, since it creates a different resource each time it is requested.
REST, when based on HTTP can benefit on standard HTTP status codes. A status code is a number that summarizes the response associated to it. The typical HTTP status code reused in REST are:
- 200 OK: The request went fine and the content requested was returned. Normally used on GET requests.
- 201 Created: The resource was created. Useful on responses to POST or PUT requests.
- 204 No content: The action was successful, but there is no content returned. Useful for actions that do not require a response body, such as a DELETE.
- 301 Moved permanently: This resource was moved to another location and the location is returned.
- 400 Bad request: The request issued has problems (for example, lacking some required parameters).
- 401 Unauthorized: Useful for authentication when the requested resource is not accessible to the user owning the request.
- 403 Forbidden: The resource is not accessible, but unlike 401, authentication will not affect the response.
- 404 Not found: The URL provided does not identify any resource.
- 405 Method not allowed. The HTTP verb used on a resource is not allowed. (for example, a PUT on a read-only resource).
- 500 Internal server error: A generic error code when an unexpected condition in the server side.
The following picture shows an example of client-server interaction with REST. The body of the HTTP messages uses JSON both for requests and responses:
