Il Re­pre­sen­ta­tio­nal State Transfer, meglio co­no­sciu­to nella sua ab­bre­via­zio­ne REST, è an­no­ve­ra­to tra i paradigmi di pro­gram­ma­zio­ne più im­por­tan­ti dello sviluppo web con­tem­po­ra­neo. Il tipo di ar­chi­tet­tu­ra, pre­sen­ta­to da Roy Fielding nel 2000 nella propria dis­ser­ta­zio­ne ha come primo scopo quello di adattare in modo ottimale le ap­pli­ca­zio­ni web alle esigenze attuali del web.

Dato che REST nel passato più recente ha gua­da­gna­to po­po­la­ri­tà e im­por­tan­za, molti operatori di progetti web cercano di ag­gior­na­re il concetto nel migliore dei modi. I risultati di questi sforzi tuttavia spesso non sono realmente “RESTful” o “conformi a REST”, poiché alcuni principi e ca­rat­te­ri­sti­che (come HATEOAS) non sono stati ade­gua­ta­men­te im­ple­men­ta­ti.

Che cos’è HATEOAS?

HATEOAS è un acronimo che sta per “Hypermedia as the engine of appli­ca­tion state” (hy­per­me­dia come motore dello stato dell’ap­pli­ca­zio­ne). Questo concetto, in­tro­dot­to da Fielding nell’ambito della sua de­fi­ni­zio­ne REST, descrive una delle proprietà decisive di REST: poiché l’ar­chi­tet­tu­ra deve offrire un’in­ter­fac­cia uni­ver­sa­le, HATEOAS richiede che il client REST possa spostarsi solo at­tra­ver­so l’ap­pli­ca­zio­ne web seguendo gli URI (Uniform Resource Iden­ti­fier) in formato iper­me­dia­le. Se questo principio viene im­ple­men­ta­to, il client necessita soltanto di una com­pren­sio­ne di base degli ipermedia per poter in­te­ra­gi­re con l’ap­pli­ca­zio­ne o il server.

La pre­pa­ra­zio­ne di singoli URI avviene come nell’esempio:

  • In forma di attributi di href e src, se si tratta di documenti HTML o di snippets
  • At­tra­ver­so attributi/elementi JSON o XML, che vengono ri­co­no­sciu­ti dai ri­spet­ti­vi client in modo au­to­ma­ti­co

Con l’im­ple­men­ta­zio­ne del principio HATEOAS, l’in­ter­fac­cia di un servizio REST si può adattare in qualunque momento, vantaggio im­por­tan­te di questa ar­chi­tet­tu­ra se comparata ad altre strutture di ap­pli­ca­zio­ni, per esempio a quelle che fun­zio­na­no sulla base di SOAP (Simple Object Acces Protocol).

HATEOAS e REST: il principio iper­me­dia­le

Per mettere a fuoco HATEOAS e il suo si­gni­fi­ca­to per REST, occorre dare uno sguardo al costrutto generale. Fielding descrive cinque principi generali da sod­di­sfa­re per ottenere un service che sia conforme a REST.

IvHMM0huDZk.jpg Per visualizzare questo video, sono necessari i cookie di terze parti. Puoi accedere e modificare le impostazioni dei cookie qui.

In ogni caso deve esserci una struttura client server che consente anche una co­mu­ni­ca­zio­ne stateless tra client e server (ogni richiesta viene quindi trattata senza ri­fe­ri­men­to a richieste pre­ce­den­ti). Inoltre il servizio deve essere costruito a più strati e uti­liz­za­re i vantaggi di HTTP caching, per rendere l’utilizzo del servizio per il client il più semplice possibile. Infine è ob­bli­ga­to­rio rea­liz­za­re la sum­men­zio­na­ta im­ple­men­ta­zio­ne di un’in­ter­fac­cia uniforme.

Per il col­le­ga­men­to tra server e client, Fielding prescrive i seguenti requisiti:

  • Chiara iden­ti­fi­ca­bi­li­tà di tutte le risorse: tutte le risorse devono poter essere iden­ti­fi­ca­te at­tra­ver­so un URI (Unique Resource Iden­ti­fier).
  • Pos­si­bi­li­tà di in­te­ra­zio­ne con le risorse at­tra­ver­so rap­pre­sen­ta­zio­ni: se un client necessita una risorsa, il server gli consegna un’ap­pro­pria­ta rap­pre­sen­ta­zio­ne (per esempio HTML, JSON o XML), in modo che il client possa mo­di­fi­ca­re o can­cel­la­re le risorse originali.
  • Messaggi au­to­de­scrit­ti­vi: ogni messaggio scambiato tra server e client deve contenere tutte le in­for­ma­zio­ni che sono ne­ces­sa­rie per la sua com­pren­sio­ne.
  • Hy­per­me­dia as the Engine of Ap­pli­ca­tion State (HATEOAS): infine il principio HATEOAS è parte ob­bli­ga­to­ria di un REST API. La struttura iper­me­dia­le sem­pli­fi­ca l’accesso dei client all’ap­pli­ca­zio­ne, poiché l’accesso e la na­vi­ga­zio­ne non ri­chie­do­no ulteriori co­no­scen­ze sull’in­ter­fac­cia.

HATEOAS è quindi una delle ca­rat­te­ri­sti­che ele­men­ta­ri dei REST API e perciò in­di­spen­sa­bi­le per qualsiasi servizio REST.

Consiglio

Troverete maggiori in­for­ma­zio­ni su REST nel nostro articolo sul tema.

HATEOAS: l’esempio di uno shop online

Per rendere il concetto di HATEOAS più ac­ces­si­bi­le, l’im­ple­men­ta­zio­ne verrà il­lu­stra­ta uti­liz­zan­do l’esempio di un negozio online. Come tipico delle pub­bli­ci­tà sul web, HATEOAS è rea­liz­za­to tramite col­le­ga­men­ti iper­te­stua­li. Questi rimandi tra due documenti o i rimandi ad altri punti del documento stesso vengono indicati in HTML come segue:

<a href="URI">Link-Text</a>

I media collegati in questo modo, come ad esempio testo, grafica, audio e video, vengono de­no­mi­na­ti Hy­per­me­dia. Le ap­pli­ca­zio­ni web ri­guar­da­no so­prat­tut­to semplici documenti di testo in formato HTML, che si possono vedere anche come “stati” (inglese: “states”) di questa ap­pli­ca­zio­ne. Nell’ambito della filosofia REST i documenti singoli sono sempre in­di­riz­za­bi­li tramite un URI univoco. Ap­pli­can­do questo concetto ad un normale negozio web, il risultato è il seguente:

Il documento che descrive lo stato “Carrello” ha un URI specifico (ad esempio 'https://example.org/carrello'). Allo stesso modo ci sono anche degli URI per i singoli articoli che vengono immessi nel carrello (come ad esempio 'https://example.org/articolo/1', 'https://example.org/articolo/2' etc). Un altro possibile stato è l’account del cliente, a cui si può accedere di­ret­ta­men­te dal carrello e che potrebbe avere il seguente URI: 'https://example.org/cliente/1'. Ogni singolo documento contiene inoltre rinvii o col­le­ga­men­ti iper­te­stua­li ad azioni che l’utente potrebbe eseguire suc­ces­si­va­men­te.

Per rimanere nello scenario pro­spet­ta­to, questo significa che il documento del carrello contiene anche rimandi agli URI degli articoli e dei clienti, i quali po­treb­be­ro a loro volta contenere altri rimandi ai pro­dut­to­ri o a documenti con­trat­tua­li. Tramite la GET request il client si muove nel negozio o in questo caso nel carrello grazie ai diversi col­le­ga­men­ti iper­te­stua­li, come mostra il seguente diagramma sem­pli­fi­ca­to:

Immagine: Esempio HATEOAS: negozio web
Rap­pre­sen­ta­zio­ne sche­ma­ti­ca della tra­spo­si­zio­ne HATEOAS in un negozio online

Con un REST service nel quale il principio di HATEOAS viene applicato come pro­spet­ta­to da Fielding, lo user deve solamente conoscere l’URI di partenza per ap­pro­fit­ta­re dell’offerta come pia­ni­fi­ca­to dallo svi­lup­pa­to­re.

Ap­pli­ca­zio­ni HATEOAS REST: esempi per la co­mu­ni­ca­zio­ne server-client

La possibile co­mu­ni­ca­zio­ne tra client e server si può spiegare sulla base della struttura del negozio web pre­ce­den­te­men­te il­lu­stra­ta. Così l’ap­pli­ca­zio­ne client fa la seguente request per ottenere una rap­pre­sen­ta­zio­ne XML dello stato del carrello:

GET https://example.org/cart HTTP/1.1

Host: https://example.org

Accept: ap­pli­ca­tion/xml

La risposta del server as­so­mi­glie­rà alla seguente:

HTTP/1.1 200 OK

Content-Type: ap­pli­ca­tion/xml

Content-Length: 256

<!--?xml version="1.0"?-->
<cart></cart>
	<cart_number>1</cart_number>
	<link rel="account" href="https://example.org/customer/1">
	<link rel="article" href="https://example.org/article/1">
	<link rel="article2" href="https://example.org/article/2">
Vai al menu prin­ci­pa­le