Presentation sur la contrainte d'architecture HATEOAS et comment le framework Spring nous facilite son implementation. Source code : https://github.com/YoannBuch/simple-spring-restbucks Fait par l'equipe de http://findtheflow.io, un outil qui permet d'analyser et visualiser des executions d'applications Java.

1. Spring HATEOAS
By Yoann Buch & Yiquan Zhou
Spring meetup 24/02/2016

2. Qui sommes nous ?
➔ 2 développeurs
➔ Lancent une entreprise autour d’un outil de développement
http://findtheflow.io
➔ Focalisent sur la visualisation et analyse des exécutions de programmes
➔ Utilisent de nombreux projets de Spring : Boot, MVC, HATEOAS,
Websocket, Integration, Batch, etc.

3. Concept

4. Humains et
hypermedia

5. Machines et
hypermedia

6. Définition

7. Modèle de maturité REST
source: http://martinfowler.com/articles/richardsonMaturityModel.html
Utiliser HTTP
Modélisation en
resources
CRUD opération
HATEOAS

8. Notre exemple d’application
Construire une API
Consulter le menu
Commander des boissons
Payer la commande
Vérifier le statut de préparation de commande
...
R E S T B U C K S
Source: “REST in Practice: Hypermedia and Systems Architecture”

9. Level 0: POX
Une URI, une methode
SOAP, XML RPC, POX
Request Response
POST /coffeeService HTTP/1.1
Content-Type: application/xml
<request xmlns=”http://restbucks.com”>
<placeOrder>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
</placeOrder>
…
</request>
HTTP/1.1 200 OK
Content-Type: application/xml
<response xmlns=”http://restbucks.com”>
<success>true</success>
<orderConfirmation>
<orderId>1234</orderId>
</orderConfirmation>
<error/>
</response>

10. Level 1: Resources
URI unique pour chaque ressource
Un seul verbe HTTP sans sémantique
Request Response
POST /orders HTTP/1.1
Content-Type: application/xml
<orderRequest>
<operation>create</operation>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
…
</orderRequest>
HTTP/1.1 200 OK
Content-Type: application/xml
<orderResponse>
<success>true</success>
<orderId>1234</orderId>
<error/>
</orderResponse>

11. Level 2: HTTP verbs
Multiples URIs, multiples verbes
Status code
Request Response
POST /orders HTTP/1.1
Content-Type: application/xml
<order>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
…
</order>
GET /orders/1234
PUT /orders/1234
DELETE /orders/1234
HTTP/1.1 201 CREATED
Content-Type: application/xml
Location: http://restbucks.com/orders/1234
<order>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
<status>payment-expected</status>
</order>

12. Hypermedia As The Engine Of Application State
Level 3 : HATEOAS
protocole Objectif
état
Transfert des liens
dans des ressources

13. Level 3: HATEOAS
Submitted Paid
Canceled
Preparing Completed
place
update
cancel
pay
check status
deliver
planned
Transition d’états d’une commande
HATEOAS => Définir les transitions d’états dans la représentation des ressources

14. Level 3: HATEOAS
Request Response
POST /orders HTTP/1.1
Content-Type: application/xml
<order>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
…
</order>
HTTP/1.1 201 CREATED
Content-Type: application/vnd.restbucks+xml
Location: http://restbucks.com/orders/1234
<order>
<customer>Mike</customer>
<location>takeAway</location>
<items>...</items>
<status>payment-expected</status>
<restbucks:link rel=”pay”
href=”https://restbucks.com/orders/1234/payment”/>
<restbucks:link rel=”update”
href=”https://restbucks.com/orders/1234”/>
<restbucks:link rel=”cancel”
href=”https://restbucks.com/orders/1234”/>
</order>

15. Formats hypermedia
Contrat pour trouver et interpréter les liens.
Formats standards:
application/xhtml+xml
application/atom+xml
application/hal+json / application/hal+xml
…
<person xmlns:atom="http://www.w3.org/2005/Atom">
<firstname>Dave</firstname>
<lastname>Matthews</lastname>
<links>
<atom:link rel="self" href="http://myhost/people/1" />
</links>
</person>
Formats specifiques:
application/vnd.mycompany.myapp+xml
application/vnd.mycompany.myapp+json
...

16. Implémentation

17. Hypermedia et Spring : Spring HATEOAS
Introduit concepts de ressources et liens
Resource(s), ResourceSupport, Link
Facilite la génération d’URIs
linkTo et methodOn
Serialize au format HAL (XML et JSON)
Facilite la consommation des liens
HalkLinkDiscoverer, Traverson
Facilite l’assemblage des ressources
ResourceAssembler

18. Liens
Link link = new Link("http://localhost:8080/something");
assertThat(link.getHref(), is("http://localhost:8080/something"));
assertThat(link.getRel(), is(Link.SELF));
Link link = new Link("http://localhost:8080/something", "my-rel");
assertThat(link.getHref(), is("http://localhost:8080/something"));
assertThat(link.getRel(), is("my-rel"));
Source : http://docs.spring.io/spring-hateoas/docs/0.19.0.RELEASE/reference/html

19. Ressources
class PersonResource extends ResourceSupport {
String firstname;
String lastname;
}
PersonResource resource = new PersonResource();
resource.firstname = "Dave";
resource.lastname = "Matthews";
resource.add(new Link("http://myhost/people"));
{
firstname : "Dave",
lastname : "Matthews",
links : [ {
rel : "self",
href : "http://myhost/people"
} ]
}

20. Générer des URIs
Link link = linkTo(methodOn(PersonController.class).show(2L)).withSelfRel();
assertThat(link.getHref(), is("http://localhost:8080//people/2")));
Découvrir et récuperer des liens
String content = "{'_links' : { 'foo' : { 'href' : '/foo/bar' }}}";
LinkDiscoverer discoverer = new HalLinkDiscoverer();
Link link = discoverer.findLinkWithRel("foo", content);
assertThat(link.getHref(), is("/foo/bar"));

21. Consommer une API hypermedia - Java

22. Consommer une API hypermedia - JavaScript
// traverson
traverson.json.from("http://api.github.com")
.newRequest()
.follow('repository_url', 'branches_url')
.withTemplateParameters({
owner: 'spring-projects',
repo: 'spring-hateoas',
branch: 'master'
}).getResource(function(err, resource) {
if (err) { console.log(err); return; }
console.log(resource);
// do something else
})
})
// jquery ajax
$.get("http://api.github.com", function(resource) {
var uri = nextUri(resource, 'repository_url')
uri = uri.replace(/{owner}/, 'spring-projects')
uri = uri.replace(/{repo}/, 'spring-hateoas')
$.get(uri, function(resource) {
uri = nextUri(resource, 'branches_url')
uri = uri.replace(/{/branch}/, '/master')
$.get(uri, function(resource) {
console.log(resource);
// do something else
})
})
})
function nextUri(resource, link) {
return resource[link]
}
https://github.com/basti1302/traverson-hal

23. HATEOAS
API explorable et auto-descriptive
➔Meilleure adoption de l’API
➔Mettre en avant des nouvelles fonctionnalités
Logique client simple
➔Pas d’URIs en dur
➔Client suit un protocole
Couplage faible entre serveur et client
➔Client résistant au changement des URIs
➔Moins de dépendences aux URI templates ou
langages de définition (ex. WSDL, WADL)

24. Pour aller plus loin
Livre : “REST in Practice: Hypermedia and Systems Architecture”
Spring Restbucks (et notre notre version simplifiee)
Bons examples en production (FoxyCart, PayPal, etc.)
Spring Data REST
HAL Browser
Spring REST Docs
CURIEs
Traitement des erreurs avec vnd.error

25. Retour d’expérience : http://findtheflow.io