REST

1
 Obiettivi

• Definire i concetti fondamentali di REST

• Comprendere i principi di progettazione
• Capire le API REST di JEE
• Analizzare esempi di applicazioni REST in Java
• Imparare a scrivere applicazioni REST in Java

REST in JEE - Concetti Fondamentali v1.4 2

 Cosa non è REST

• Non è un framework
• Non è una tecnologia
• Non è una specifica

REST in JEE - Concetti Fondamentali v1.4 3

 Cos’è REST

• Stile architetturale descritto da Roy Fielding

• ben documentato
• con vincoli
• con best practices
• REpresentational State Transfer
• Gestisce rappresentazioni di risorse
• http://acme.com/product/XCHG34G
• Lo stato risiede nel client
• Il client transferisce lo stato accedendo alle rappresentazioni
REST in JEE - Concetti Fondamentali v1.4 4
 Cos’è uno “stile architetturale”?

• Insieme coordinato di vincoli

• sui ruoli e le caratteristiche degli elementi dell’architettura
• sul modo in cui si relazionano
• Uno stile può essere applicato a molte architetture
• Un’architettura può consistere in molti stili

REST in JEE - Concetti Fondamentali v1.4 5

 Client - Server

• Il classico “client-server” è uno stile architetturale

• separa le responsabilità dell’interfaccia da quelle
della persistenza
• permette portabilità su client multipli
• facilita la scalabilità
• permette evoluzioni distinte sui due strati

REST in JEE - Concetti Fondamentali v1.4 6

 Vincoli aggiuntivi di REST

• Statelessness
• Non c’è stato conversazionale del client sul server
• Ciascuna richiesta dal client
• deve contenere tutte le informazioni necessarie all’elaborazione
• non deve fondarsi su uno stato conversazionale pre-esistente
• non deve fondarsi sulla sequenza di richieste precedenti

REST in JEE - Concetti Fondamentali v1.4 7

 Stato conversazionale sul client

• Tutto lo stato conversazionale dunque risiede

interamente sul client
• Modellato sulla struttura del web
• “Representational State Transfer is intended to evoke
an image of how a well-designed Web application
behaves: a network of web pages (a virtual state-
machine), where the user progresses through an
application by selecting links (state transitions),
resulting in the next page (representing the next
state of the application) being transferred to the
user and rendered for their use.”
REST in JEE - Concetti Fondamentali v1.4 8
 Motivazioni

• Replicare il modello di successo del web

• Riutilizzare tool tipici del web (p.es. cache sul browser)
• Facilitare ridondanza ed alta affidabilità sui server
• ilconversazionale
failover non deve gestire lo stato
sul server
• laconversazionale
scalabilità non deve gestire lo stato
sul server
• Facilitare il monitoraggio
• ogni richiesta è comprensibile senza contesto
REST in JEE - Concetti Fondamentali v1.4 9
 Inconvenienti

• Performance sulla rete potenzialmente ridotta

• Ridotto controllo di consistenza da parte del server
• p.es. ogni richiesta va re-validata interamente
• Non è facile

REST in JEE - Concetti Fondamentali v1.4 10

 Caratteristiche

• Client/Server: l’iniziativa è asimmetrica

• Stateless: il server è senza stato conversazionale
• Cache: grazie alle URL usate come chiave
• Uniform Interface: pochi verbi fondamentali
• GET, POST, PUT, DELETE
• Named Resources, attraverso le URL
• Interconnected resource representation: grazie alle URL
• Layered Components: sono permessi proxy,
gateway, cache, decoratori, ecc...

REST in JEE - Concetti Fondamentali v1.4 11

 Cacheability

• I dati nelle risposte vanno classificati

• cacheable
• not cacheable
• Nel primo caso, i client sono autorizzati a evitare
nuove richieste di risorse mappate su URL identiche
• rispettando vincoli (p.es. data di scadenza)
• Questo migliora l’efficienza, la scalabilità e la performance
• In certi casi permette anche operazioni disconnesse
REST in JEE - Concetti Fondamentali v1.4 12
 Vincoli sulle risorse

• Le risorse vanno identificate

• Non vengono manipolate direttamente, ma
attraverso loro rappresentazioni
• I messaggi devono essere auto-descrittivi
• HATEOAS: Hypermedia AsThe Engine Of Application State
• approfondito dopo

REST in JEE - Concetti Fondamentali v1.4 13

 Risorse

• Una risorsa è una mappatura concettuale di un

insieme di entità
• Può cambiare nel tempo
• Una risorsa può essere una collezione di risorse
• Ogni risorsa dev’essere identificata univocamente
• attraverso un nome - la sua URI
• simile al concetto di chiave primaria
• il nome non deve cambiare nel tempo
• se proprio deve, raramente
• se ha senso, anche la sua versione è una risorsa
REST in JEE - Concetti Fondamentali v1.4 14
 URI

• REST non ha vincoli su come progettare le URI

• Ma ci sono alcune raccomandazioni
• non necessariamente contengono un significato
• ma se sono leggibili facilitano la vita
• va scelto uno schema di nomi consistente
• Usare nomi, non verbi
• OK: http://acme.com/product/XCHG34
• KO: http://acme.com/product?getProd=XCHG34
REST in JEE - Concetti Fondamentali v1.4 15
 URI

• Non usare parametri per l’identificazione

• OK: http://acme.com/product/XCHG34
• KO: http://acme.com/product?id=XCHG34
• I parametri possono essere usati per condizionare
la rappresentazione restituita…
• http://acme.com/product/XCHG34?details=full
• … o identificare sottoinsiemi di collezioni
• http://acme.com/product?from=11&count=10
REST in JEE - Concetti Fondamentali v1.4 16
 Rappresentazioni

• Una rappresentazione non è una risorsa

• Una stessa risorsa può avere rappresentazioni
multiple
• a livello di dettaglio
• a livello di formato
• p.es. HTML, XML, JSON, PDF, JPG, PNG
• REST non vincola i formati
• REST sfrutta i formati standard esistenti
REST in JEE - Concetti Fondamentali v1.4 17
 Interludio: strumenti per il testing

• I browser vanno bene per testare GET

• Per tutti gli altri verbi HTTP, è necessario uno
strumento diverso
• A riga di comando: curl
• incluso in tutte le distribuzioni Un*x
• Applicazione (o estensione di Chrome): Postman
• http://www.getpostman.com/
• Prima di proseguire, analizzare alcuni esempi
REST in JEE - Concetti Fondamentali v1.4 18
 curl

• curl -v http://acme.com/foo/bar
• curl -v -X POST -H"Accept: application/json” -d “…
json…” http://acme.com/foo/bar
• curl -v -X PUT http://acme.com/foo/bar2

REST in JEE - Concetti Fondamentali v1.4 19

 Postman

REST in JEE - Concetti Fondamentali v1.4 20

 Interludio: blueMarine II

• Preparazione
• Scaricare da https://bitbucket.org/tidalwave/bluemarine2-src
• %% mvn -DskipTests

cd modules/REST

% mvn -Prun-service
• URL da provare con GET
• http://...:9999/rest/record
• http://...:9999/rest/record/
urn:bluemarine:record:eLWktOMBbcOWysVn6AW6kk
sBS7Q=
• http://...:9999/rest/track
REST in JEE - Concetti Fondamentali v1.4 21
 Interludio: Jersey Example

• Preparazione
• %% mvn -DskipTests

cd JerseyExampleServer

% mvn tomcat7:run
• Definire headers
• user: marco.rossi@email.it
• password: marco
• Accept: application/json
• Eseguire POST su http://localhost:8080/rest/user/login
• Prendere nota del token

REST in JEE - Concetti Fondamentali v1.4 22

 Interludio: Jersey Example

• Eliminare headers user e password

• Aggiungere header
• X-TOKEN: <token>
• Eseguire GET http://localhost:8080/rest/folder

REST in JEE - Concetti Fondamentali v1.4 23

 Interludio: CustomerDB

• CustomerDB, dagli esempi di NetBeans

• Provare
• http://localhost:8080/CustomerDB/
• Provare le risorse
• http://.../CustomerDB/webresources/
entities.customer
• http://.../CustomerDB/webresources/entities.customer/2
• Provare JSON
• curl --header "Accept: application/json" <url>
• Provare il WADL
• http://.../CustomerDB/webresources/application.wadl
REST in JEE - Concetti Fondamentali v1.4 24
 Negoziazione del formato

• Spesso è auspicabile che il server supporti formati

diversi, tra i più popolari
• La negoziazione dovrebbe avvenire seguendo la
specifica HTTP
• Accept: text/xml;q=0.5, application/json
• Non si dovrebbero usare parametri…
• KO: http://acme.com/product/XCHG34?format=json
• … o altre informazioni
• KO: http://acme.com/product/XCHG34.json
REST in JEE - Concetti Fondamentali v1.4 25
 Auto-descrittività dei messaggi

• Non c’è descrizione formale del formato dei

messaggi
• non c’è un WSDL come nei Web Services, che
descrive sia i messaggi che le rappresentazioni
• In certi casi, si può usare quella fornita dallo standard
• p.es. con XML si può usare un XSD
• Inpergenerale
caso
la cosa va gestita e documentata caso

• Si può usare un MIME-Type applicativo

• Content-Type: application/vnd.my-great-stuff
REST in JEE - Concetti Fondamentali v1.4 26
 Interfaccia uniforme

• REST non è RPC o SOA

• non si modella il comportamento a partire da un
elenco di operazioni arbitrarie
• le operazioni permesse sono sempre le stesse
• sono i verbi HTTP
• Non confondere REST con “Pseudo-REST”

REST in JEE - Concetti Fondamentali v1.4 27

 Interfaccia uniforme

• Le manipolazioni di una risorsa sono definite dalle

classiche operazioni CRUD
• Create (Insert)
• Retrieve (Select)
• Update
• Delete

REST in JEE - Concetti Fondamentali v1.4 28

 Verbi HTTP

• GET: recupera una risorsa (retrieve)

• deve essere idempotente (no effetti collaterali)
• PUT: aggiorna una risorsa (update)
• DELETE: cancella una risorsa (delete)
• POST: crea una risorsa (create)
• OPTIONS: descrive i verbi disponibili

REST in JEE - Concetti Fondamentali v1.4 29

 Operazioni

• REST vincola all’uso esclusivo di queste operazioni

• vanno usate in modo consistente
• non vanno usate altre operazioni (p.es. mappate
nelle URL)
• Semplificazione
• della semantica
• della complessità del client
• del modello applicativo
• Di nuovo, è importante perché altre infrastrutture
(p.es. una cache) si comportino in modo coerente
REST in JEE - Concetti Fondamentali v1.4 30
 Usare i codici di stato HTTP

• HTTP definisce una ricca collezione di codici di

stato per indicare l’esito di un’operazione
• 200: operazione ok
• 401: richiesta autorizzazione
• 404: risorsa non esistente
• 503: momentaneamente non disponibile
• È necessario usare i codici standard
• non inventarsi alternative codificate nel
messaggio
• altrimenti altre infrastrutture coinvolte, p.es. una
cache, non possono trarne profitto
REST in JEE - Concetti Fondamentali v1.4 31
 REST è il “database di internet”

• Espone risorse così come un database espone tabelle o viste

• ma disaccoppiate (rappresentazioni, non risorse)
• Generalmente è più facile comprendere modelli di
dati che non procedure

REST in JEE - Concetti Fondamentali v1.4 32

 HATEOAS

• Hypermedia As The Engine Of Application State

• Secondo Roy Fielding è parte integrante di REST
• Spesso trascurato

REST in JEE - Concetti Fondamentali v1.4 33

 Hypermedia

• Estensione logica del termine “hypertext” che indica

l’integrazione per mezzo di link tra testi, grafica,
immagini statiche, video, suoni

REST in JEE - Concetti Fondamentali v1.4 34

 Il modello del web

• Ricordiamo
stati
l’analogia tra REST, web e macchine a

• le pagine di un sito sono gli stati

• i link sono transizioni di stato, auto-descrittive
• ogni pagina vincola le possibili transizioni alla
successiva
• il client decide quali link seguire
• c’è una pagina nota di inizio navigazione
REST in JEE - Concetti Fondamentali v1.4 35
 Vincoli di HATEOAS

• Ogni endpoint REST dovrebbe esporre una singola

URI iniziale
• l’endpoint è una singola risorsa, collezione di tutte le altre
• La rappresentazione associata alla URL dovrebbe
contenere link auto-descrittivi alle altre risorse
• usando p.es. <link rel=“xyz” … />
• Recupero incrementale delle rappresentazioni
• ma ogni singola risorsa è bookmarkabile
• Modello gerarchico
REST in JEE - Concetti Fondamentali v1.4 36
 Semantiche di relazione
• Quale dizionario definisce la semantica di rel?
• questa semantica è definita modo formale?
• questa
macchina?
semantica è comprensibile da una

• Web Semantico
• Troppo complesso per la maggior parte dei casi
• Usare definizioni semplici, specifiche, documentate
• p.es. RDFa Lite in HTML 5 definisce uso di attributi
• rel, src, href
• aggiunge attributi
• property, content, datatype, typeof
REST in JEE - Concetti Fondamentali v1.4 37
 Progettazione di applicazioni REST

• Viste le premesse dovrebbe essere chiaro che…

•… usare tecnologie legate a REST (p.es. un
framework)…
•… non garantisce di per sé la creazione di
un’applicazione REST
• (certamente può aiutare)
• Èconsistente
necessario progettare l’applicazione in modo

REST in JEE - Concetti Fondamentali v1.4 38

 Linee guida

• Definire le risorse e le loro relazioni

• Definire le loro rappresentazioni
• XML? Con XSD? JSON? etc…
• Definire i loro identificativi
• Ogni tipo di risorsa ha un controllore
• Le operazioni del controllore sono solo CRUD (o
sottoinsieme)

REST in JEE - Concetti Fondamentali v1.4 39

 Esempi

• Trasformare verbi in nomi

• “Approvare una transazione”
• non è un’operazione “approve” applicata a
“transaction”
• KO: GET http://acme.org/transaction/txid?
op=approve&detail=…
• è“transaction”
creare una risorsa “approval” relazionata a

• OK: POST http://acme.org/transaction/txid/approval/id

• I dettagli sono nella rappresentazione di “approval”
REST in JEE - Concetti Fondamentali v1.4 40
 Eccezioni alla regola

• Secondo Roy Fielding…

• “Cookie interaction fails to match REST's model of
application state, often resulting in confusion for the
typical browser application.”
• I cookie rompono il modello stateless
• Tuttavia i cookie possono essere molto utili
• per esempio per la sicurezza
• Usare compromessi
• non memorizzare l’intero stato conversazionale
nel cookie
• solo lo strettamente necessario
REST in JEE - Concetti Fondamentali v1.4 41
 Esempio: OAuth

• Il token è un header
• Authorization: Bearer 1/fFAGRNJru1FQd44AzqT3Zg
OAuth 2.0 v1.0 42
 REST in JEE6+
• Basato sulla JAX-RS API
• Classi annotate implementano le risorse mappate su URL
• @ApplicationPath globale
• @Path per ogni risorsa root
• Metodi annotati rispondono ai verbi
• @GET, @POST, @PUT, @DELETE
• Annotazioni per i MIME type
• @Consumes, @Produces
• Annotazioni per i parametri
• @PathParam usata con @Path(“/product/{id}”)
• @QueryParam usata con parametri nel metodo
• @CookieParam per i cookie
• @FormParam per le form
REST in JEE - Concetti Fondamentali v1.4 43
 Creazione della risposta

• JAX-RS serializza automaticamente entity JAXB

• Alternativamente
con fluent API
Response o ResponseBuilder

• Response.ok(entity, mimeType).build();
• Response.status(403).build();
• Response.accepted(entity).build();
• Response.notModified().build();
• Response.temporaryRedirect(url).build();
• ecc...
• Usare appropriatamente gli stati HTTP
REST in JEE - Concetti Fondamentali v1.4 44
 WADL

• Web Application Description Language

• SOAP : REST = WSDL : WADL
• Linguaggio interpretabile da software che descrive
la struttura di una webapp REST
• Descrive le risorse, i metodi e gli schema
• Creato da Sun, non standardizzato
• Automaticamente generato da Jersey (JAX-RS
reference implementation)
• http://…/context/application.wadl
• https://wadl.java.net/
• wadl2java (due tool distinti) genera un client Java
REST in JEE - Concetti Fondamentali v1.4 45
 Esercizio 1

• Scrivere un servizio REST e deployarlo

• Testarlo con un browser
• Testarlo con curl o Postman
• Nota per Eclipse: aggiungere tutti i “*.jar” nella
distribuzione jaxrs-ri-2.6.zip

REST in JEE - Concetti Fondamentali v1.4 46

 Esercizio 2

• Scrivere un client REST con Jersey

REST in JEE - Concetti Fondamentali v1.4 47

 Riepilogo

• Domande e risposte

REST in JEE - Concetti Fondamentali v1.4 48