TL; DR
Representational state transfer or simply REST is a term for exchanging data in well-defined formats in order to increase interoperability. Through the application of certain restrictions, a decoupling between clients and servers must be achieved, which makes the former more stable, and the latter more flexible for changes.
A resource representation is the result of applying a mapping from the current state of the resources to a well-defined syntax and structure of multimedia types. Therefore, it is closely related to content matching , which defines the process of media type matching to transform the state of resources into the requested view (= syntax and structure).
REST can be considered as a method that allows you to separate clients from servers / APIs in a distributed system, which gives server freedom the opportunity to develop and change its structure in accordance with its needs, without violating the implementation of the client.
To get such a strong benefit, you need to create a couple of preconditions, since almost nothing comes for free. Here, Fielding identified a couple of limitations that he further clarified (and explained) in his well-known blog post . Servers cannot achieve such freedom if clients do not follow the REST approach, and clients cannot dynamically explore further possibilities if the server does not support clients in such situations. In short, both sides must follow the same principles. If this approach is not followed, the direct connection between the server and clients will remain, which will lead to failures if the server ever changes.
But how is separation really achieved?
First, the server must support the client in carrying out its tasks, including URIs that clients can use. The presence on the server of all URIs that the client can call from the current state in which the client is located eliminates the need for the client to know the API and the structure of the URI in advance.
Second, instead of allowing clients to interpret URIs, servers should return URIs in conjunction with link relationship names. Those. instead of a client using (and interpreting) a URI like http://server.org/api/orders , it should use a link relation like new-order . If the server changes the above URI to something like http://server.org/api/new-orders for any reason, clients using link relationship names will still be able to perform their task, while for those who using the URI directly, an update is required before they can continue.
To my knowledge, there are still no standards in which such link names should be defined and documented. For collection links, the semantics of relationship names, such as self , prev , next , first and last , seem quite significant, although something more specific to the subject area, such as order or product-xyz , may not matter. Such semantics can be described either in special types of media, or in new standards.
So far, these points are about the HATEOAS limitation, but unfortunately that's not all. According to a Fieldings blog post:
The REST API should spend almost all of its descriptive efforts on defining the types of media used to represent resources and managing the state of the application, or on defining extended relationship and / or hypertext markup names for existing standard media types.
Field further comment that:
The REST API should never have "typed" resources significant to the client. Specification authors can use resource types to describe the server implementation behind the interface, but these types must be irrelevant and invisible to the client. The only types that are relevant to the client are the current media type representations and standardized relationship names.
A typed resource is a resource in which the client has an assumption of content. That is, the client who received the http://server.org/api/user/sam+sample URI with the link relationship name user determines that the data belonging to this resource describes the person and therefore may try to streamline the presentation of the application/json data resource in the Person object.
The problem with typed resources is that clients have certain pre-assigned assumptions or knowledge regarding the data contained in such resources, that is, a user resource that can vary from server to server. While one server can provide a username as a name property, another server can use firstName and lastName , and the client that wants the server practically does not support every possibility. In addition, if the server ever changes its logic, clients may break with a certain probability. To counteract this type of communication, media types should be used.
Media types, which are a human-readable textual description of the presentation format, determine the syntax used, as well as the structure and semantics of the available elements contained in documents exchanged in this format. Therefore, applications conforming to the REST architectur model should use installed or custom media types to increase compatibility. Instead of directly connecting the client and server, both are actually associated with media types. Support for these types of media can be provided either by loading existing libraries, or by implementing the specification from scratch. Even loading these types of media dynamically through plugins is possible, if supported.
Clients and servers should use content negotiation to negotiate a common multimedia format that both parties understand, to share the current state of the resource. Content negotiation is achieved by providing an HTTP Accept header (and / or one of its native elements) that lists the MIME types that the client can or wants to process within the request and the server responding to one of the requested formats, including the HTTP Content-Type response header Content-Type to inform the client about which media type representation was actually used, or to return a 406 failure response.
For the user example above, clients can send an Accept HTTP header with the following contents: application/vcard+json, application/hal+json;q=0.6, application/json;q=0.1 server, which asks the server to return the state of the resource in the syntax and structure defined by one of the listed media. types. In addition, it indicates that the client prefers to receive a state formatted in accordance with the specification for the media type description application/vcard+json , and if the server cannot do this, it should prefer hal + json over the traditional json syntax. The server now either displays the current state of the resource in one of the requested formats, or responds with a corresponding 406 error message if either all the requested media types are unknown, or the state cannot be converted to such a structure or the default presentation is supported by the client.
Summarizing, we can say that REST is a method used to achieve high interoperability, relying on clearly defined types of multimedia and for branching clients from servers using features such as content negotiation and HATEOAS. As a reward, customers will be resistant to changes and, therefore, need less maintenance in general, while the server gets the opportunity to evolve and change without fear that customers will not be able to interact with it as soon as the changes take effect.
Certain things, such as standardized meaningful names for link relationships, custom domain-specific media types, and mapping processes to convert state to applicable representations of media types, should be set up first, which is a non-trivial task of TBH, although, while available, they provide the above advantages.