In what do consist the misunderstandings about the "REST" word and its meaning [closed]
Asked Answered
D

2

8

It is not always easy to figure out what is really a RESTful application and/or api, because there is a sort of misunderstanding about the REpresentational State Transfer architectural style meaning and scopes.

Initially, I was quite in trouble with what, the adjective "REpresentational" of the acronym REST, referred to. This was because "representational state" sounded to me not so well...

Further, I was impressed also by a blog post of the author of this architectural style, Roy Fielding, where he is a lot disappointed about the frequent misunderstanding that api based on http verbs are RESTful, in particular he complaints about the coupling among client and server of these api regarding their names and data structures.

I want to try to give only a theoric explanation about REST arch. style and I'd like to know other points of view.

Droop answered 7/6, 2016 at 15:51 Comment(0)
D
9

First part

My main goal is to focus attention on the reason for the name "representational state transfer".

I think that the most of misundertandings about the REST goes under the adjective "representational". Most people think that "representational" word relates to the resource state and so builds application focusing on object structures to communicate/transfer to the calling clients.. but I think that the focus is the "transfer", it is the transfer to be"representational", and so it is important design applications (or api) that make use of the "representational" ability of the REST network system on that they rely, to support transfers among client-server components.

To figure out the whole question about the concern of the REST architectural style, it needs to understand that the author, Roy Fielding, intended to suggest in his dissertation, a set of architectural principles to build architectures based on the hipertext or hipermedia paradigm, and so this paradigm is the central key to understand this important topic.

Behind the style of organizing a client-server application's architecture proposed by Roy Fielding, I think there is a specific idea of a modern client-server application, that consists by a sort of engine to govern application state transition, whose states are potentially extensible to infinite.

In this vision, the Ipertext\Ipermedia is the center of the whole architectural style proposed by Fielding and the key concept that allows this paradigm to work is the "representational (state) transfer".

So we can understand why the word "representational" refers to the concept about the "transfer", instead of the concept about "state". Because it is the transfer to be representational (of a representational type), and this means that it is the system that manages the "transfers" and on which relies the client-server interaction, to give some standard indication about the representation, that is the media-type concept (or MIME in the web implementation of the REST) and that is, in my opinion, the main cause of the name "Representational State Transfer".

So, designing a Restfull application, it is design first an architecture based on a web of components, each of them comunicates with others in a client-server layered architecture model, sending each of them a representation of its state.

And so, the front-end, the first client of this architecture, transits through its states showing rapresentation of the states sended by the component, or components, that it calls endorsing on a uniform consistent interface and not on a "private" api.

A such type of application, in the mind of the author, is potentially extensible to infinite states, because its states don't depend on a private api, but depend on a univoque identifier system (as URI) shared by all agents in this architecture, on a few some verbs to manage transion of its states and on an agreed shared representational transfer system, or plus.

This transition ends with communication of its representation to the called server component via the verbs that compose the "public" api, which should belong to the stateless communication protocol used by the client-server components.

In such a way, this client-server components interaction consists in interchanging (transferring, communicating) of standardized representations (media types) of components states, based on use of a stateless protocol.

And the core concept that allows all these architectures to potentially extend itself to infinite is the decoupling of component's resources structures and names with their client identifying and representation (representational transfer).

Second part

further details on mediatype and RESTful application building

I think that the original intuition of Fielding was been the idea that a key feature to allow full decoupling between client and server components in a distributed application architecture, and indefinitely extensible, was the definition of an open and evolving standard representations set, and thus the ability of these components to exchange such representations and in the case of the client to interpret them.

That's why "representational transfer"!

Namely, transfers based on standardized rappresentations. Instead, "state" is precisely what is represented in the standard way because it is understood by any client component that supports REST principles, and allows the representation itself to be the engine of the state transitions containing in its mediatype representation also the standard information handling, which them should refer to a small set of standard verbs related to the client-server communication protocol.

Therefore, to build applications (or connectors from the point of view of REST) adhering to the standard REST and therefore RESTful, means:

  1. designing uri for own resources;

  2. making these uri always available into representations sended to the clients;

  3. focusing in design the most appropriate media type representations to support own application flow, and so the same state transitions.

This means to support any type of media on any type of device and also support any type of interaction system or transition states (eg automated systems not only user)

Droop answered 7/6, 2016 at 15:51 Comment(5)
I think that a constructive comment is more useful of an unmotivated downvote.. tank youDroop
Haven't downvoted, but I find this explanation to be rather recursive and repetitive. You go on about '"representational" referring to state' without seemingly ever getting into a really good explanation of what that really means… Just my 2€¢.Horseshit
Maybe you haven't read my explanation as you state that I "go on representational referring to state".. I say that representational refers to transfer.. it would be better if you read before "constructively" commenting. Thank youDroop
I have read it and that's what I came away with. Your bold section in the first paragraph and the bold one in the middle essentially repeat the same information… I was trying to leave constructive criticism, leave it if you don't like it.Horseshit
Thank you very much for your suggestions, I will consider them for a revision of my post.. but I insist, if you state that I said that representational refers to state, you are wrong, and a lot.. because the main motive that pushed me to write this post it is exactly this wrong assumption.. further, the second bold section details what is in the first bold.. if you read my post and comment about the real content, I would appreciate it a lotDroop
J
5

Although I think that the post is obviously better suited for programmers, as this is a general concept discussion, I will try and give it a shot.

To me, REST is a transfer of state or data currently contained in a certain resource from a server to a client or vice versa. This transfer is initialized by the client through invoking certain operations, the underlying communication protocol provides, on a resource. The representation aspect is now the returned style/flavor/type of the state/data. If a client requests something like Accept: "application/hal+json", "application/json", "text/html" it directly ask the server for a representation of the state in either of the three formats (with preference on the leading ones) and the server can decide, based on his capabilities, which one to return. Certain weight preferences can be specified also to boost the likelihood of the server to return this media-type rather then an other more general one.

REST by its simplicity is actually hard to implement in reality, more on that later. Besides some architectural constraints Roy Fielding put in place, the given link includes a further list of things that have to be respected in order to call a service or API RESTful which have been summarized in the following list:

  • The API should adhere to and not violate the underlying protocol. Altough REST is used via HTTP most of the time, it is not restricted to this protocol.

  • Strong focus on resources and their presentation via media-types.

  • Clients should not have initial knowledge or assumptions on the available resources or their returned state ("typed" resource) in an API but learn them on the fly via issued requests and analyzed responses. This gives the server the opportunity to move arround or rename resources easily without breaking a client implementation.

Especially the last rule given by Roy Fielding is often violated by not letting the client discover resources as the endpoint is coded into the client/application explicitely. Also the type returned is often pre-assigned. This results in plenty of URI-design related questions here at StackOverflow as the URI needs to carry the semantics in order for the developer to put them into the client.

But also the media type is often restricted to only support application/json or application/xml although they don't carry any semantics on the actual content. XML especially was designed to be eXtensible, hence the X in its name. There are already plenty of special XML based types out there, tough frameworks often return just application/xml which puts burden onto the client of knowing what the response semantically means.

Plain XML and JSON however do not convey any semantics on the actual content or define rules that support clients in their understanding. They just describe the syntax a client can use to spot what elements a response contains and what data they contain, nothing more, nothing less.

Atom/RSS and Json-HAL are often recommended to at least enhance the HATEOAS requirements as they provide links to other resources and therefore help a client to semantically grasp that a certain string has to be interpreted as further resource which it can act upon. Though, the clients still does not really know what data it actually processes. Therefore special media types should be developed which support clients in understanding what the data is all about - and they may have different flavors for the same resource state, i.e. one giving just an overview presentation on the resource state while an other media type might contain the full set of data.

This, in my opinion, led Fielding to the following statement:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.

The thing REST tries to introduce is a clear decoupling from clients to a specific API set, like a web browser is not coupled to a specific web server. A web browser is capable of presenting large numbers of HTML pages filled with images or other media types without breaking. The decoupling is achieved by letting a client start from a base URL and then explore new possibilities via interpreting responses. HATEOAS is therefore what drives the clients state change through following links given by the server on a previous request. A change on the server side does therefore not brake any true RESTful clients as they will only use what they learned from a previous response. A client which expects resource X to be loacated at path Y and have state Z will, with high certainty, break on a server change.

The media types is, to me, the knowledge base of a client and teaches her what to do with a certain document that states being of this type. A browser i.e. will render a HTMl page so it is actually readable for humans. It will also dynamically change the representation using JavaScript code and registered events. Certain downloaded bytes might be shown as picture, some will be interpreted as video while other types might spawn a certain object that handles the content (like certain video-players, flash-players or applets).

The real-world problem is now: How to write those media-types that an arbitrary client is able to actually understand. By arbitrary I mean something like an automated system which has no a-priory knowledge of the API or service and thus has to learn everything via request/responses. As state and its representation may come in many different flavors, teaching the client how the data should be interpreted is the tough thing. Semantical processing of data is still a huge research-field. An automated system needs to know that certain strings have a certain semantic and that something in a template URI returned by a server needs an input that fulfills this semantic.

A list of more or less well-known, registered media types can be found at IANA. Where possible, it is recommended to use one of these media types (if suitable) to avoid reinventing the wheel all over again. Certain use cases however might require a custom format and thus require additional overhead (designing, implementing and eventually registering the media type at IANA may take some time).

As reaction to this shortcommings many implementors try to go the simple route and put the knowledge into the client which is then tightly coupled to the API and wont easily react to changes on the API itself. For us humans, it is rather trivial to grasp the intent of an URI, hence we insist on a clean URI-API. Users have certain pre-assumption (based on the naming or some documentation) what the API is capable of and therefore reduce REST to a marketing term.

The misconception plenty of people out there have, is, like Fielding said, that an API which works on HTTP is considered to be RESTful. Also the Richardson maturity model is not that helpful on this issue as well as that the StackOverflow community treats everything that is somehow related to API over HTTP as REST.

Jeminah answered 3/9, 2016 at 14:23 Comment(1)
Thanks for your answer @Roman.. in fact when I posted this topic the first time I didn't know well StackOverflow and the StackExchange network and now I also think that perhaps this topic would have been better on programmers (I will ask for stackoverlflow meta ..) . I find your post very nice and I agree with your general view of REST. I continue on my OP...Droop

© 2022 - 2024 — McMap. All rights reserved.