The Web architecture has influenced the REST genesis and the way other kinds of distributed systems are created. In its essence the Web is based on these fundamental principles (architectural style):
- Resource Representation
- Resource State
- Resource Address
REST Context
Resource Representation
A resource is the basic building block of a distributed system (and the Web) and represents anything that a service can expose such as a document, a video or a business process. What is exposed is not the actual resource but its representation. This representation is encoded in one or more transferrable formats such as HTML, XML, JSON, plain text, JPEG and so on. A simple example is a Web page.
A service accesses a resource representation never the underlying resource. This separation allows loose coupling between a client application and the service and also allows scalability because a representation can be cached and replicated.
Each representation is a view of the same actual resource, with transfer formats negotiated at runtime through a content negotiation mechanism.
Resource State
A service progresses by transitioning from one state to another like in a state machine. The key difference is that in the service the possible states and the transitions amongst them are not known in advance. As the service gets to a new state, the next possible transitions are discovered.
For example, in an hypermedia system the states are defined by uniquely identifiable resources. The identifiers of the possible states to transition are contained in the current (state) representation as hyperlinks. Hence the name Representational State Transfer (REST).
Resource Address
A service can act on a resource (i.e., representation) through a very well defined set of verbs as provided by the HTTP protocol. For more information, see HTTP 1.1 rfc 2616. This set provides a uniform interface or a small number of verbs with well defined and widely accepted semantics to meet the requirements of a distributed system.
To act upon a resource the service must be able to identify it unequivocally. Tis is done through the Uniform Resource Identifier (URI). A URI uniquely identifies a resource and makes it addressable or capable of being manipulated using a protocol such as HTTP.
A URI takes the following form:
http://scheme-specific_structure
For example
http://myserver/croissants/chocolate-truffle
establishes that the URI must be interpreted by the service according to the HTTP scheme. Notice that the previous URI does not specifies the resource format.
Best Practices
It is good practice not to specify the format in the URI by adding a suffix to the resource such as .html or .xml or .jsp. It is the responsibility of the service to provide the correct format as specified by the client in the Accept attribute of the HTTP request header (content negotiation). This allows loose coupling between the client and the service.
Using HTTP Verbs
The following examples show how to use HTTP verbs to access resources exposed by a Web service.
The service used is the public available HTTP Request & Response Service.
HEAD
Request
To obtain header info, in your console enter the following command:
curl -I httpbin.org
Response
The execution of the previous command produces this output:
HTTP/1.1 200 OK Connection: keep-alive Server: gunicorn/19.7.1 Date: Wed, 25 Apr 2018 23:46:15 GMT Content-Type: text/html; charset=utf-8 Content-Length: 13129 Access-Control-Allow-Origin: * Access-Control-Allow-Credentials: true X-Powered-By: Flask X-Processed-Time: 0 Via: 1.1 vegur
GET
Request
To perform a GET request, in your console enter the following command:
curl -X GET httpbin.org
Response
The execution of the previous command produces the page content at the specified URL:
<html>
<head>
<meta http-equiv='content-type' value='text/html;charset=utf8
<meta name='generator' value='Ronn/v0.7.3 (http://github.com/
<title>httpbin(1): HTTP Client Testing Service</title>
......
</html>
PUT
Request
To perform a GET request, in your console enter the following command:
curl -X PUT httpbin.org
Response
The execution of the previous command produces the following response:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <title>405 Method Not Allowed</title> <h1>Method Not Allowed></h1> The method is not allowed for the requested URL.
Service Maturity Level
A maturity model has been created to classify services as highlighted next.
- Level 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.
- Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.
- Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.
For more information, see Maturity Model.
See also Representational State Transfer (REST) APIs Part 4 of 4.