Download - API Hypermedia - Devoxx 2015
Sample presentation
API Hypermedia
API Hypermedia
twitter.com/_dmartin_
www.ippon.frDirecteur du Ple Conseil
Linus Torvalds a dit...
Bad programmers worry about the code. Good programmers worry about data structures and their relationships.
Objectifs
Comprendre le rle des relations hypermdiadans les API Web
3...2...1 Go!
Dfinition
Quappelle ton API Web ?
Une interface... exploitant les technologies du web permettant dinteragir avec des donnes
Here, There and Everywhere!
On parle des API partout !Phnomne de mode ?ou tout simplement adapt aux usages ?
Qui n'a pas son API en 2015 ?Toutes les startups cools ont leur APILes grands du net ont leur APIMme les institutions ouvrent leurs API !
Pourquoi?
Pourquoi cet essor ?
Simple
Rapide
Adapt aux use cases actuels
A la mode (aussi)
As easy as ABC...
Crer son API semble simple :
Choisir un framework (spcialis ou gnraliste)Dfinir quelques ressourcesEcrire un peu de conf...
Tada!
Quelques [unit de temps variable] plus tard
/users/{uid}/friends, /hotels/{hotel}/bookings/{booking}
GET, PUT, POST, DELETE, ...
Accept: application/json, Authorization: Bearer c3DF...
200 OK, 201 Created, 401Unauthorized, 403 Forbidden, 404 Not Found, ...
{"user_id":1,"name":"Chris Rivers", "nickname":"chris"}
Avec une jolie doc
GET /users{?page}Retourne les utilisateurs 10 par 10 (voir Pagination).Exemple de rponse :[{"id":"23423423","firstname":"Roy","lastname":"Trenneman"}, {...}]
Pagination :Paramtre : page (optionnel)Valeur : un entier positif dcrivant le numro de la page afficher[...]
So what?
Une API de ce type semble normale
Imaginons maintenant la mme chose pour un site web...
Facebook sans relation hypermdia
Notice de Facebook :
Pour accder aux profils individuels de vos amis, compltez cette adresse :
https://www.facebook.com/{usernickname}
...
Google sans relation hypermdia
Notice de Google :
Pour effectuer une recherche, compltez cette adresse :https://www.google.fr/search?q={mots_clef}
Pagination :Chaque page contient 10 documents. Pour naviguer parmi l'ensemble des rponses, utilisez cette adresse :https://www.google.fr/search?q={mots_clef}&start={item_nb}...
Le web sans relation hypermdia
Le speaker : Avez-vous envie d'apprendre crire les URL spcifiques de chaque site ?!?La salle : Non !Le speaker : Et pourquoi ?La salle : Inutile : il suffit decliquer sur les liens proposs !
Le web est hypermedia
Tout est connectNavigation intuitiveDcouverte des nouveautsAdaptation au changement
Le web sans relation hypermdia
Cot client (browser)
Votre navigateur sait suivre des liens TOUT SEULIl comprend ce que chacun lui apporte TOUT SEUL
A t'il besoin d'une quelconque intelligence? NON
Back to the roots...
REST
Style darchitecture aussi mconnu que connuPourtant introduit en 2000 (o tiez-vous il y a 15 ans ?)Concepts pour architectures distribues prennesContraintes respecter, certaines optionnelles, d'autres obligatoires comme le fait de reposer sur les relations hypermdia !
Wasn't this clear enough?
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint?
REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution
R. Fielding (http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven)
Richardson Maturity Model (Qcon 2008)
Niveau 3 : Hypertext As The Engine Of Application State
Niveau 2 : Utilisation correcte des verbes HTTP
Niveau 1 : Notion de ressources
Niveau 0 : RPC like WS-* style...
RTFM WTF!
Pourquoi une API hypermedia ?
Sans relation hypermdia :Hardcoder les chemins
Connatre les flows
Client limit, trs coupl l'API Impossible d'voluer sans risque!
Pourquoi une API hypermedia ?
Avec relation hypermdia :Dcouvrir les relations et leur sens
Consommer au lieu de construire
Dtecter les variations, informer et sadapter
Client plus robustevolutions plus simples introduire
Real life stories...
GET /users/1234{"name":"Roy Trenneman"}L'API hypermedia illustre
GET /users/1234{"name":"Roy Trenneman", "links":[{"url":"/users/1234/friendz", "rel":"friends"}]}GET /users/1234{"name":"Roy Trenneman", "links":[ {"url":"/users/1234/friends", "rel":"friends"}, {"url":"/users/1234/ppl", "rel":"pplUMayKnow"} ]}Documentation:URL vers les amis = /users/{uid}/friendz
+
Premier constat
Premier constat
Pas besoin dun client complexe L'API dispose de souplesse pour voluer
Le client consomme ce dont il a besoinIl ne cre pas les URLIl peut avertir de nouveauts non comprises (new features!!!)
{ [...] "links": [{"rel":"v1:user", "href":"/toto/userZ"}] [...]}L'API hypermedia illustre
{ [...] "links": [ {"rel":"v1:user","href":"/toto/userZ","deprecated":"true"}, {"rel":"v2:user","href":"/new_users/"} ] [...]}
Cration d'une ressource
POST /people{"name" : "Jen Barber"}
HTTP/1.1 201 CreatedContent-Location: http://[...]/abcde
{representation}
201 + Content-Location + reprsentation
Le header Link (RFC5988)
Link: ; rel="next", ; rel="last"Header Link: Approche alternative pour exprimer des relations
Exemple GitHub API :
A noter: Link-Template (draft IETF)
La reprsentation polyforme
{ "inStock": { "value":"true", "type": "embedded" }}Embedded & Remote
Le client comprend les notions embedded et remote Il s'adapte aux rponses L'API choisit le mode optimal (User-Agent, ...)
{ "inStock": { "value":"http://[...]/prodId/avail", "type": "remote" }}
Application Workflow 1/2
"product": { "uid": "REF-0123456789", "name": "Cool Product", "links": [ {"rel": "add-to-cart", "href": "https://mysite.com/customer/1234/cart-items/3333", "method": "PUT"}, {"rel": "remove-from-cart", "href": "https://mysite.com/customer/1234/cart-items/3333", "method": "DELETE"}, {"rel": "add-to-wishlist", "href": "https://mysite.com/customer/1234/whishlist/3333", "method": "PUT"} ]}
Application Workflow 2/2
L'API prend en compte le contexte :Li aux ressources et leur tat
Li l'utilisateur courant (permissions, )
Li d'autres paramtres (maintenance, ...)
Et construit un flow adapt
PAS le client !
Mais... ne serait-ce pas ?
Permettre de modifier ltat de lapplication en exposant les transitions possibles sous forme de liens hypermdia
HATEOAS!
Buzzword detected!
Reprsentation plus complexe
Constat: Reprsentation enrichie
No more POJO migrateur Modle simpliste : rserv des usages limits
Il faut:Transporter des donnes
Transporter des mtadonnes
Quel formalisme adopter?
Quels sont les formats possibles?Quel est le format adapt?
Media types anyone?
Les media types
Formats sous lesquels des ressources sont reprsentes
Exprimer le format souhait (client serveur)
Informer sur le format retourn (serveur client)
Les media types courants
Les classiquestext/html
application/javascript
text/css
image/png
...
Les classiques des APIapplication/xml
application/json
Quel rle pour le media type ?
Un mdia type pour une API hypermedia doit :
Dfinir une structure (donnes + mta donnes)
Prendre en charge les relations hypermedia
tre ouvert (accessible, volutif, document, ...)
Mauvaise nouvelle...
Mauvaise nouvelle : pas de standard
Bonne nouvelle
Bonne nouvelle : ce n'est pas (trop) grave
Quel media type hypermedia?
2 approches possibles: crer son format ou en adopter un1 approche conseille: en adopter un!
Collection+JSON, HAL, JSON API,Hydra, JSON-LD, Siren, Uber, NARWHL, ...
Collection+JSON
{ "collection" : { "version" : "1.0", "href" : "http://example.org/friends/", "links" : [...], "items" : [...], "queries" : [...], "template" : {...}, "errors" : {...} } }
Hypermedia Application Language (JSON)
{ "_links": {"self": { "href": "/orders" }, ...} }, "property1": 14, "propery2": 20, "_embedded": { "embedded_obj1": [{ "_links": {...}, "prop1": 30.00, "prop2": "USD", "prop3": "shipped" }] }}Existe aussi au got XML
Siren
{ "class": [ "order" ], "properties": { ... }, "entities": [ ... ], "actions": [ { "name": "add-item", "title": "Add Item", "method": "POST", "href": "http://api.x.io/orders/42/items", "type": "application/x-www-form-urlencoded", "fields": [ { "name": "prop1", "type": "hidden", "value": "42" } ] } ], "links": [ ... ]}
In the trenches...
Happy CRUD everyone!
Le paysage actuel
Frameworks "CRUD-like API"
Souvent orients "POJO migrateur"
Mais lorsqu'il s'agit des aspects plus intressants...
Are we doomed Sir?
Pas de solution clef en main...
Mais des micro-librairies spcialises
Spring Hateoas, Siren4j, HALBuilder,Jersey Declarative Linking, HALselhof
N'oublions pas l'objectif d'une API Web
Une API Web est cre pour tre consomme
Les clients doivent donc comprendre les reprsentations:Savoir en extraire les donnes
Et les mta-donnes
Le paysage cot client
Des initiatives plus ou moins connues
Traverson, hyperagent.js, angular-hal, Spring HATEOAS, HALBuilder, RESTfulie (R.I.P.), ...
Mais aussi : JSON Path !
Last lap...
En synthse
Aucune obligation... Sauf le bon sens ?Cot et complexit - relatifs - considrer
MAIS des gains la clefFlexibilit
Prennit
Robustesse
Le mot de la fin...
Use your brain:Dont design-by-buzzword
Dont believe everything you read
Always keep in mind that change is inevitable
Roy Fielding - 2008 - A little REST and relaxation
Merci!
Q & A
@YourTwitterHandle#YourSessionHashtag
@_dmartin_#hapiClick to edit the title text formatTexte du titre
@YourTwitterHandle#YourSessionHashtag
@_dmartin_#hapiClick to edit the title text formatTexte du titre
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelTexte niveau1Texte niveau2Texte niveau3Texte niveau4
Texte niveau 5
@_dmartin_#hapi
Click to edit the title text formatTexte du titre
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelTexte niveau1Texte niveau2Texte niveau3Texte niveau4
Texte niveau 5
@YourTwitterHandle#YourSessionHashtag
Click to edit the title text formatTexte du titre
@YourTwitterHandle#YourSessionHashtag
Click to edit the title text formatTexte du titre
@YourTwitterHandle@YourTwitterHandle
@_dmartin_#hapi
@_dmartin_#hapi
Click to edit the title text formatTexte du titre
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelTexte niveau1Texte niveau2Texte niveau3Texte niveau4
Texte niveau 5
@YourTwitterHandle#YourSessionHashtag
Click to edit the title text formatTexte du titre
@_dmartin_#hapi
@YourTwitterHandle#YourSessionHashtag
Click to edit the title text formatTexte du titre
@YourTwitterHandle@YourTwitterHandle
@_dmartin_#hapi
@YourTwitterHandle#YourSessionHashtag
Click to edit the title text formatTexte du titre
Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelTexte niveau1Texte niveau2Texte niveau3Texte niveau4
Texte niveau 5
@_dmartin_#hapi