Un'introduzione pragmatica a REST e al suo utilizzo con Jersey

1. REST con Jersey
Fabio Bonfante
bonfante.fabio@gmail.com

2. Cosa vuol dire REST
“Representational State Transfer”
chiaro no?

3. Definizione di REST
● Fielding, Roy Thomas (2000),
“Architectural Styles and the Design of
Network-based Software Architectures”
MA
● Ognuno ormai ha la sua “definizione”

4. Un'idea (forse) comune
● Software architectural style
● Ogni cosa e' una risorsa e ha un identificativo
(tipicamente un URL)
● Server (il più possibile) senza stato
● Applicata soprattutto per i web-services
(SOAP non ci piace più)
● Sfrutta meglio il protocollo HTTP
(vedi PUT e DELETE questi “sconosciuti”)
● Benvenuto JSON

5. Un esempio di API REST

6. Un esempio di API REST
POST
create
GET
read
PUT
update
DELETE
delete
/dogs
Nuovo
cane
Lista di
tutti i cani
Aggiornamento
massivo
Cancellazione
di tutti i cani
/dogs/313 3rR0r
Mostra
“Pluto”
Se esiste,
aggiorna Pluto
Cancella Pluto

7. REST con Jersey
● Specifica JAX-RS
The Java API for RESTful Web Services
(JSR-311)
● Implementazione di riferimento
● Versioni
– 1.18 (legacy...)
– 2.x (attualmente 2.9)

8. Jersey: la ragion d'essere
● Mapping chiamate HTTP a metodi di
oggetti POJO
● Restituire nel formato richiesto:
– Content-type negotiation (Es. XML, JSON,....)

9. Jersey overview
● Deployment
– Web container: Servlet 2.x e 3.x, filter
– HTTP Server
– JEE, OSGI
● Configurazione tramite:
– JAX-RS class: Application
– Jersey class ResourceConfig
● JAX-RS Client + connectors:
– Apache HTTP, Jetty, Grizzly Asynchronous
● Test Framework (no JAX-RS)

10. Mapping: annotazioni base
● @Path("/dogs”)
● @GET, @PUT, @POST, @DELETE
● @Produces, @Consumes
– @Produces("application/json")
– @Produces({"application/xml",
"application/json"})

11. Mapping: parametri
● @PathParam
– @Path("/users/{username}")
– @Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")
● @QueryParam
– GET http://example.com/dogs?limit=100
● @FormParam
@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("name") String name) {
// Store the message
}

12. Support JSON
● Varie librerie:
– MOXy (jersey 2.x preferred)
– Jackson
– Jettison
– Java API for JSON Processing (JSON-P)
● Modalità
– POJO based JSON binding (MOXy and Jackson)
– JAXB based JSON binding
– Low-level JSON parsing & processing
(Jettison, e JSON Processing API da JEE7+)

13. Supporto JSON – MOXy
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-moxy</artifactId>
<version>2.9</version>
</dependency>
● Autodiscover se presente nel classpath
● Supporta anche XML con annotazioni JAXB

14. Supporto JSON – Jackson
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-json-jackson</artifactId>
<version>2.9</version>
</dependency>
● Va registrato tra le features di Jersey
● Va configurato un ObjectMapper
● Dicono che forse è il più veloce...

15. Supporto XML
– javax.xml.transform.stream.StreamSource
– javax.xml.transform.stream.SAXSource
– javax.xml.transform.stream.DOMSource
– org.w3c.dom.Document
● JAXBElement<MyBean>
Se non voglio usare @XmlRootElement

16. Ricezione multipart
<dependency>
<groupId>org.glassfish.jersey.media</groupId>
<artifactId>jersey-media-multipart</artifactId>
<version>2.9</version>
</dependency>
Da registrare esplicitamente in Jersey
@PUT @Path("{id}/image")
@Consumes(MediaType.MULTIPART_FORM_DATA)
public String setImage(
@PathParam("id") Long id,
@FormDataParam("file") InputStream uploadedInputStream,
@FormDataParam("file") FormDataContentDisposition
fileDetail) {
return saveImage(uploadedInputStream);
}

17. Dependency Injection
<dependency>
<groupId>org.glassfish.jersey.ext</groupId>
<artifactId>jersey-spring3</artifactId>
<version>2.9</version>
</dependency>
● Bean Spring come risorse e provider Jersey
● Iniettare in Jersey bean di Spring (non da XML!)
Il ciclo di vita delle risorse Jersey è
gestito da Jersey

18. Gestione eccezioni
Facebook
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803) Some of the
aliases you requested do not exist: foo.bar"}
Twilio
HTTP Status Code: 401
{"status" : "401", "message":"Authenticate","code": 20003, "more
info": "http://www.twilio.com/docs/errors/20003"}
SimpleGeo
HTTP Status Code: 401
{"code" : 401, "message": "Authentication Required"}

19. Gestione eccezioni
@Provider
public class AppExceptionMapper implements
ExceptionMapper<AppException> {
@Override
public Response toResponse(AppException ex) {
return ResponseBuilder.userException(ex);
}

20. REST best practices
● Risorse: nomi (meglio concreti) e non verbi
● Associazioni:
– GET /owners/5678/dogs
GET /dogs/byOwner/5678
oppure GET /dogs/?owner=5678
MOLTO MEGLIO!!!
ma... perchè?

21. REST best practices
● E' complicato con Jersey gestire le risorse
gerarchicamente
● I client si aspettano che:
“/owners/....” restituisca degli “Owners”
● È un concetto assimilabile ai Dao che già conosciamo
● Permette di nascondere la complessità sotto ‘?’
“Da una Risorsa derivano (grandi)
oggetti di quel tipo!”

22. EXTRA: REST best practices
● Mai rilasciare un API senza versione!
● Operazioni puramente funzionali:
– /convert?from=EUR&to=CNY&amount=100
– Usare VERBI
– Documentare che NON sono risorse
● Sottodominio specifico per le API
● ChattyAPIs: quante chiamate servono?
● Occhio alle gerarchie di Resources

23. Perchè ci/mi piace REST
● Lato server
– Mapping chiaro funzioni esposte
– Scalabilità se gestito bene lo stato
● Lato client web
– Librerie JS con concetto resource (es.
AngularJS)
– JSON “nativo” nei browser
– Più dinamicità ed efficienza nei client

24. Perchè mi piace REST
● Lato client mobile
– JSON piu' leggero di XML
– HTTP Tools che parlano
● Integrazione
– Più semplice (bastano “curl” o “wget” da shell)
– Servizi più raggiungibili (evviva la porta 80!!!)
– Aggregazione di servizi da provider diversi per
creare innovazione
– Monetizzazione della propria Business Logic

25. Da studiare/curiosità
● WADL
● HATEOS
● EclipseLink: JPA Entities Through RESTful
Services

26. Chi RESTa per la
?