Representational State Transfer

Representational State Transfer (abbreviated REST , more rarely ReST ) describes a programming paradigm for distributed systems , especially for web services . REST is an abstraction of the structure and behavior of the World Wide Web . REST aims to create a style of architecture that better represents the demands of the modern web. REST differs from other architectural styles primarily in the requirement for a uniform interface (see the Principles section ).

The purpose of REST is primarily machine-to-machine communication . REST is a simple alternative to similar methods like SOAP and WSDL and the related method RPC . Unlike many related architectures, REST does not encode any method information in the URI , since the URI specifies the location and name of the resource, but not the functionality that the Offering web service to the resource. The advantage of REST is that a large part of the infrastructure required for REST (e.g. web and application servers, HTTP -capable clients, HTML and XML parsers, security mechanisms) is already available in the WWW, as well as many web - Services are RESTful per se. A resource can be represented using different media types , also called representation of the resource .

An online service that only offers unchanged page content based on the HTTP Internet standard is already REST-compliant. However, dynamically generated pages often do not follow this paradigm. For example, news sites offer constantly changing information with both different formats and content that are difficult to process automatically. If the format remained unchanged, an important REST property would be fulfilled. For example, a website on which the current time is always available in the same format would be REST-compliant.

The term "Representational State Transfer" is intended to illustrate the transition from the current state to the next state of an application. This state transition takes place through the transfer of the data that represent the next state.

history

The REST paradigm evolved from the HTTP Object Model designed by Roy Fielding in 1994 . Fielding developed his idea of ​​a unified concept over the years until he published the REST architectural style as part of his dissertation in 2000 . The programming paradigm of the "RESTful Application" was often implemented incorrectly and has only recently (as of 2014) found acceptance in the world of the World Wide Web. In his work, Fielding goes into the various requirements that are important for web architecture.

Principles

The architecture style refers to six properties that a service must have. It is not specified how these principles must be implemented.

Client server

The general requirement is that all properties of the client-server architecture apply. The server provides a service that can be requested by the client if required.

Statelessness

Each REST message contains all the information that is necessary for the server or client to understand the message. Neither the server nor the application should store state information between two messages. Therefore, it is called a stateless (English: stateless ) protocol. Each request from a client to the server is self-contained in that it contains all the information about the application status that is required by the server to process the request.

Statelessness in the form described here favors the scalability of a web service. For example, incoming requests can be easily distributed to any machine in the course of load balancing : Since each request is self-contained and application information is therefore only stored on the client side, no session management is required on the server side. In practice, many HTTP-based applications therefore use cookies and other techniques to keep status information on the server side. The failure safety is also favored because the statelessness requires that transactional data transmission takes place in a single page view.

Caching

HTTP caching should be used, but the following applies: A request that does not have to be made is the fastest request.

Uniform interface

This is the main differentiator from all other architectural styles. This consists of four other properties. The aim is the uniformity of the interface and thus its ease of use.

Addressability of resources

Any information identified by a URI is identified as a resource. Every RESTful service has a unique address, the Uniform Resource Locator (URL). This “street and house number in the network” standardizes the access path to offer a web service for a variety of applications (clients). Consistent addressability also makes it easier to continue using a web service as part of a mashup .

Representations for changing resources

The services accessible at one address can have different forms of representation. A RESTful server can deliver different representations of a resource depending on what the application is requesting, e.g. B. in different languages ​​or formats ( HTML , JSON or XML ) or the description or documentation of the service. The change of a resource (i.e. its current status) should only take place via a representation.

Self-descriptive messages

REST messages should be self-describing. This includes u. a. the use of standard methods. Resources can be manipulated using these standard methods. The HTTP verbs are an example here; Details see below.

"Hypermedia as the Engine of Application State" (HATEOAS)

According to Fielding, this is the most important property; see below .

Multi-tier systems

The systems should be structured in several layers. This means that it is sufficient to simply offer the user an interface. The levels behind can remain hidden, thereby simplifying the overall architecture.

Code on Demand (optional)

This fielding requirement is optional. Code on demand means that code can only be transferred to the client for local execution when necessary.
An example of this would be the transfer of JavaScript code in an HTML representation.

implementation

A stateless client-server protocol is used to implement the REST paradigm. The main application layer protocols used are HTTP and HTTPS . One of the reasons for this is that they have become established on the WWW, have a comparatively simple structure and are compatible with almost every firewall . REST unifies the interface between systems to a manageable and standardized set of actions with regard to the expected behavior. What these actions are is not specified in REST, but all actions are generally defined, usually by the application layer protocols used.

While REST as an abstraction of the WWW does not require any special implementation or any special protocol, it can be observed that HTTP is used almost exclusively, which also defines the number of actions.

Accessed via HTTP, so is the HTTP method used, including GET, POST, PUTand DELETE, which operation is desired the service. HTTP requires that GET"safe" ( English safe ) must be, which means that this method obtains information only and does not cause other effects. The methods GET, HEAD, PUTand DELETEmust, according to HTTP specification idempotent be what, in this context means that the multiple sending the same request is no different effect than a single call.

REST clients that use HTTP can issue the following commands to request or change resources:

Command (HTTP method)	description	Remarks
GET	Requests the specified resource from the server. GET has no side effects. The state on the server is not changed, which is why GET is called secure .
POST OFFICE	Inserts a new (sub) resource below the specified resource. Since the new resource does not yet have a URI, the URI addresses the higher-level resource. As a result, the new resource link is returned to the client. In a broader sense, POST can also be used to map operations that are not covered by any other method.
PUT	The specified resource is created. If the resource already exists, it will be changed.
PATCH	Part of the specified resource is changed. Side effects are allowed here.
DELETE	Deletes the specified resource.
HEAD	Requests metadata about a resource.
OPTIONS	Checks which methods are available on a resource.
CONNECT	Is used to route the request through a TCP tunnel. Mostly used to establish an HTTPS connection via an HTTP proxy.
TRACE	Returns the request as received by the target server. Serves, for example, to determine changes to the request by proxy servers.
↑ a b c d e nullipotent . Calling these methods does not have any side effects. ↑ not idempotent. Calling again creates a new object for each call with the same URI instead of returning the same object. ↑ a b idempotent . Calling these methods for the first time with a specific URI has side effects. A repeated call with the same URI does not lead to any further side effects. ↑ see RFC 5789 ↑ a b c d e optional. Not required for CRUD operations. ↑ a b Implementing these methods may have an impact on the security of the application.

Depending on the implementation, other HTTP commands can be supported. These include COPY, MOVE, MKCOL, LOCKand UNLOCKthe WebDAV protocol, as well as LINKand UNLINKfrom RFC 2068 . When communicating over UDP also can CoAP from 7252 RFC be used instead of HTTP, which is slightly different meanings for GET, POST, PUTand DELETEhas.

safety

The paradigm requires that all information an application needs to restore the page state be included in the request. The URI identifies the resource, while the HTTP header can contain information such as the type of access (GET, PUT), return format or authentication.

REST can be used for websites and web services that do not require authentication or that can be achieved in other ways (e.g. by checking the IP address , HTTP authentication or TLS / HTTPS certificate checking), which already covers many use cases. Alternatively, token- based methods such as HMAC , OAuth , JSON Web Token or OpenID can be used.

Since REST - in contrast to SOAP with WS-Security  - does not define any encryption methods itself, an encrypted transport protocol such as HTTPS is used for security-critical messages .

Versioning

To version a REST service, there are several options to choose from: via the DNS address, URL and via the HTTP header.

With DNS versioning , the version is treated as part of the DNS domain.

http://v1.api.foo.com/customer/1234
http://v1_1.api.foo.com/customer/1234
http://v2.api.foo.com/customer/1234
http://v2_2.api.foo.com/customer/1234

This variant is usually associated with a lot of effort because of the management in the DNS. It is therefore rarely found in practice.

With URL versioning , the version of the interface is specified in the path of the URL:

http://foo.com/api/v1/customer/1234
http://foo.com/api/v1.1/customer/1234
http://foo.com/api/v2.0/customer/1234
http://foo.com/api/v2.2/customer/1234

Versioning via the URL is the most common variant.

When versioning via the HTTP header , the version is specified in the Accept HTTP header:

GET /api/customer/1234 HTTP/1.1
Host: foo.com
Accept: application/xml,application/json;version=1

After the provision of a new version of the service, the old version of the endpoint must continue to be made available for a certain period of time in order to give the user time to switch. A client application should be able to automatically recognize that the endpoint is obsolete without restricting the use of the endpoint. This can be done using a warning HTTP header :

HTTP/1.1 200 OK
Date: Sat, 11 Mar 2017 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Warning: 299 foo.com/api/v1 "Deprecated API : use foo.com/api/v1.1 instead. Old API maintained until 2017-06-02"
Content-Length: 88
Content-Type: application/json
Connection: Closed

The client should log the warning in the log and in an OpsDB to enable the client operator to switch to the new API in good time.

If the old endpoint is still offered, the new endpoint should be able to be found using an HTTP redirect at the old address:

GET /api/v1/customer/1234 HTTP/1.1
Host: foo.com
Accept: application/xml,application/json

HTTP/1.1 302 Found
Location: foo.com/api/v1.1/customer/1234

In principle, it is advisable to use monitoring to check whether this endpoint is still being actively used before releasing an obsolete endpoint . In addition, OpsDB should be used to check whether it is an endpoint that is rarely used (e.g. quarterly).

HATEOAS

Hypermedia as the Engine of Application State ( HATEOAS ) is a design principle of REST architectures. With HATEOAS, the client of a REST interface navigates exclusively via URLs that are provided by the server.

Depending on the chosen representation, the URIs are made available via hypermedia , e.g. B.

• in the form of “href” and “src” attributes for HTML documents or HTML snippets, or
• in JSON or XML attributes / elements defined and documented for the respective interface.

In abstract terms, HATEOAS-compliant REST services represent a finite machine , the state of which is changed by navigation using the URIs provided.

HATEOAS guarantees a loose connection and the interface can be changed. In contrast, a SOAP-based web service communicates via a fixed interface. To change the service, a new interface must be provided here and defined in the interface description (a WSDL document). Registration databases or similar infrastructures, e.g. B. are required for Remote Function Call , are not required for HATEOAS.

There are different standards for mapping HATEOAS. These include:

• JSON API
• JSON-LD and Hydra
• Collection + JSON
• Siren

example

The example shows a GET request that calls up account information in JSON format:

GET /accounts/123abc HTTP/1.1
Host: bank.example.com
Accept: application/json
...

The answer can then be as follows:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

{
   "account": {
      "account_id": "123abc",
       "balance": {
          "currency": "EUR",
          "value": 100.0
       },
       "links": {
          "deposit": "/accounts/123abc/deposit",
          "withdraw": "/accounts/123abc/withdraw",
          "transfer": "/accounts/123abc/transfer",
          "close": "/accounts/123abc/close"
       }
   }
}

This answer contains four possible links: deposit(deposit), withdraw(debit), transfer(transfer) and close(cancel). If the account is overdrawn, money can only be deposited into the account, but none can be debited or transferred, and the account can no longer be canceled. The answer for this example can therefore look like this:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ...

{
   "account": {
      "account_id": "123abc",
       "balance": {
           "currency": "EUR",
           "value": -100.0
       },
       "links": {
          "deposit": "/accounts/123abc/deposit"
       }
   }
}

Richardson Maturity Model

The Richardson Maturity Model ( RMM , German Richardson maturity model ) is a benchmark developed by Leonard Richardson that specifies how strictly a service implements REST.

Richardson Maturity Model

Level	properties
0	uses XML-RPC or SOAP the service is addressed via a single URI uses a single HTTP method (often POST)
1	uses different URIs and resources uses a single HTTP method (often POST)
2	uses different URIs and resources uses several HTTP methods
3	is based on HATEOAS and therefore uses hypermedia for navigation uses different URIs and resources uses several HTTP methods

Differentiation from other communication mechanisms

REST is a programming paradigm that can be implemented with various mechanisms. One innovation is the use of as many HTTP methods as possible in connection with the action to be carried out. In contrast, SOAP, for example, is essentially used with the POST method. The difference lies more in the broader use of HTTP as a protocol and URI as an identification mechanism for concrete objects. In contrast, in the past SOAP interfaces were set up based on RPC . The weaknesses of SOAP include the rather large overhead with a lot of meta and little user data, as well as the computationally intensive building of XML messages. In addition, there are now numerous sub-standards that are difficult to survey. In contrast, the strict requirements of REST help to build well-structured services and support the use of clean URLs .

See also

• Java API for RESTful Web Services (JAX-RS)
• Web Application Description Language - description language for REST-based services
• JSON-RPC - JSON based RPC protocol
• Open Data Protocol (OData)
• OpenAPI - Specification for describing REST interfaces

literature

• Leonard Richardson, Sam Ruby: Web Services with REST . O'Reilly Verlag, 2007, ISBN 978-3-89721-727-0 .
• Stefan Tilkov et al .: REST and HTTP . Development and integration according to the architectural style of the web. 3rd, updated and expanded edition. dpunkt Verlag, 2015, ISBN 978-3-86490-120-1 .

Web links

• Roy Thomas Fielding: Architectural Styles and the Design of Network-based Software Architectures. Retrieved April 6, 2013 (English, dissertation describing REST). 
• Roy Thomas Fielding: REST APIs must be hypertext-driven. September 20, 2008, accessed on April 7, 2013 (recommendations for designing REST interfaces with HATEOAS). 
• David Megginson: The quick pitch. In: Quoderat. February 15, 2007, accessed April 6, 2013 (English, Pragmatic Recommendations for the Use of REST). 
• Thomas Bayer: REST Web Services. Orientation in Objects , November 2002, accessed April 6, 2013 (Introduction to RESTful Web Services). 
• Alex Rodriguez: RESTful Web services: The basics. In: developerWorks. IBM , November 6, 2008, accessed April 6, 2013 (Basic Principles of REST). 
• Stefan Tilkov: REST - the better web service? In: jaxenter. IT-Republik, February 2009, accessed on April 6, 2013 (Basics of the REST architecture). 
• Gregor Roth: RESTful HTTP in practice. InfoQ, August 18, 2009, accessed April 6, 2013 (English, REST in practice). 

Individual evidence

1. ^ Roy Fielding: 6: Experience and Evaluation. In: Architectural Styles and the Design of Network-based Software Architectures. 2000, accessed June 15, 2015 . 
2. ^ Roy Thomas Fielding: Architectural Styles and the Design of Network-based Software Architectures. (PDF) In: Dissertation. 2000, accessed September 11, 2017 . 
3. ↑ Fielding, R. (2000) pp. 79ff
4. ↑ Fielding, et al .: 9 Method Definitions. In: Hypertext Transfer Protocol - HTTP / 1.1. 2004, accessed July 1, 2010 . 
5. ^ WebDAV Methods. In: MSDN. Microsoft, June 2007, accessed February 13, 2016 . 
6. ↑ Andreas Würl, Jörg Adler: Highest level of maturity for REST with HATEOAS. Heise , December 6, 2016, accessed December 7, 2010 . 
7. ↑ Kevin Sookocheff: On choosing a hypermedia type for your API - HAL, JSON-LD, Collection + JSON, SIREN, Oh My! March 11, 2014, accessed June 11, 2017 . 
8. ^ Martin Fowler : Richardson Maturity Model. March 18, 2010, accessed April 7, 2013 (English, explanation of the REST Maturity Model (RMM)). 
9. ↑ Martin Helmich: RESTful Webservices (1): What is that anyway? March 12, 2013, accessed November 16, 2017 .