Best Practices for RESTful Web Services Development

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)