API Hypermedia - Devoxx 2015

@_dmartin_#hapi
API Hypermedia

@_dmartin_#hapi
API Hypermedia
twitter.com/_dmartin_
www.ippon.fr
Directeur du Pôle Conseil

@_dmartin_#hapi
Linus Torvalds a dit...
“Bad programmers worry about the code. Good programmers worry
about data structures and their relationships.”

Objectifs
Comprendre le rôle des relations hypermédia
dans les API Web

@YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi
3...2...1… Go!

@_dmartin_#hapi
Définition
Qu’appelle t’on API Web ?
Une interface...
… exploitant les technologies du web
… permettant d’interagir avec des données

@_dmartin_#hapi
Here, There and Everywhere!
On parle des API partout !
Phénomène de mode ?
ou tout simplement adapté aux usages ?
Qui n'a pas son API en 2015 ?
Toutes les startups cools ont leur API
Les grands du net ont leur API
Même les institutions ouvrent leurs API !

@_dmartin_#hapi
Pourquoi ?
Pourquoi cet essor ?
Simple
Rapide
Adapté aux use cases actuels
A la mode (aussi)

@_dmartin_#hapi
As easy as ABC...
Créer son API semble simple :
Choisir un framework (spécialisé ou généraliste)
Définir quelques ressources
Ecrire un peu de conf...

@_dmartin_#hapi
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, 401 Unauthorized, 403 Forbidden, 404 Not Found, ...
{"user_id":1,"name":"Chris Rivers", "nickname":"chris"}

@_dmartin_#hapi
Avec une jolie doc
GET /users{?page}
Retourne les utilisateurs 10 par 10 (voir Pagination).
Exemple de réponse :
[{"id":"23423423","firstname":"Roy","lastname":"Trenneman"}, {...}]
Pagination :
Paramètre : page (optionnel)
Valeur : un entier positif décrivant le numéro de la page à afficher
[...]

@_dmartin_#hapi
So what?
Une API de ce type semble normale…
Imaginons maintenant la même
chose pour un site web...

@_dmartin_#hapi
Facebook sans relation hypermédia
Notice de Facebook :
Pour accéder aux profils individuels de vos amis, complétez cette
adresse :
https://www.facebook.com/{usernickname}
...

@_dmartin_#hapi
Google sans relation hypermédia
Notice de Google :
Pour effectuer une recherche, complétez cette adresse :
https://www.google.fr/search?q={mots_clef}
Pagination :
Chaque page contient 10 documents. Pour naviguer parmi l'ensemble
des réponses, utilisez cette adresse :
https://www.google.fr/search?q={mots_clef}&start={item_nb}
...

@_dmartin_#hapi
Le web sans relation hypermédia
Le speaker : “Avez-vous envie d'apprendre
à écrire les URL spécifiques de chaque site ?!?”
La salle : “Non !”
Le speaker : “Et pourquoi ?”
La salle : “Inutile : il suffit de
cliquer sur les liens proposés !”

@_dmartin_#hapi
Le web est hypermedia
Tout est connecté
Navigation intuitive
Découverte des nouveautés
Adaptation au changement

@_dmartin_#hapi
Le web sans relation hypermédia
Coté client (browser)
Votre navigateur sait suivre des liens… TOUT SEUL
Il comprend ce que chacun lui apporte… TOUT SEUL
A t'il besoin d'une quelconque intelligence ? NON

Back to the roots...

@_dmartin_#hapi
REST
Style d’architecture aussi méconnu que connu
Pourtant introduit en 2000… (où étiez-vous il y a 15 ans ?)
Concepts pour architectures distribuées pérennes
Contraintes à respecter, certaines optionnelles, d'autres
obligatoires…
… comme le fait de reposer sur les relations hypermédia !

@_dmartin_#hapi
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)

@_dmartin_#hapi
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...

@_dmartin_#hapi
Pourquoi une API hypermedia ?
Sans relation hypermédia :
●
Hardcoder les chemins
●
Connaître les flows
Client limité, très couplé à l'API
→ Impossible d'évoluer sans risque !

@_dmartin_#hapi
Pourquoi une API hypermedia ?
Avec relation hypermédia :
●
Découvrir les relations et leur sens
●
Consommer au lieu de construire
●
Détecter les variations, informer et s’adapter
Client plus robuste
Évolutions plus simples à introduire

Real life stories...

@_dmartin_#hapi
GET /users/1234
{"name":"Roy Trenneman"}
L'API hypermedia illustrée
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+

@_dmartin_#hapi
Premier constat
Premier constat
→ Pas besoin d’un client complexe
→ L'API dispose de souplesse pour évoluer
Le client consomme ce dont il a besoin
Il ne crée pas les URL
Il peut avertir de nouveautés non comprises (new features!!!)

@_dmartin_#hapi
{
[...]
"links" : [{"rel":"v1:user", "href":"/toto/userZ"}]
[...]
}
L'API hypermedia illustrée
{
[...]
"links" : [
{"rel":"v1:user","href":"/toto/userZ","deprecated":"true"},
{"rel":"v2:user","href":"/new_users/"}
]
[...]
}

@_dmartin_#hapi
Création d'une ressource
POST /people
{"name" : "Jen Barber"}
HTTP/1.1 201 Created
Content-Location: http://[...]/abcde
{representation}
201 + Content-Location + représentation

@_dmartin_#hapi
Le header Link (RFC5988)
Link: <https://api.github.com/search/code?q=something&page=2>;
rel="next", <https://api.github.com/search/code?
q=something&page=4>; rel="last"
Header Link : Approche alternative pour exprimer des relations
Exemple GitHub API :
A noter : Link-Template (draft IETF)

@_dmartin_#hapi
La représentation polyforme
{
"inStock": {
"value":"true",
"type": "embedded"
}
}
Embedded & Remote
→ Le client comprend les notions « embedded » et « remote »
→ Il s'adapte aux réponses
→ L'API choisit le mode optimal (User-Agent, ...)
{
"inStock": {
"value":"http://[...]/prodId/avail",
"type": "remote"
}
}

@_dmartin_#hapi
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"}
]
}

@_dmartin_#hapi
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 paramètres (maintenance, ...)
Et construit un flow adapté
PAS le client !

@_dmartin_#hapi
Mais... ne serait-ce pas ?
Permettre de modifier l’état de l’application en exposant les
transitions possibles sous forme de liens hypermédia…
HATEOAS!
Buzzword detected!

@_dmartin_#hapi
Représentation plus complexe
Constat : Représentation enrichie
No more “POJO migrateur ©”
→ Modèle simpliste : réservé à des usages limités
Il faut :
●
Transporter des données
●
Transporter des métadonnées

@_dmartin_#hapi
Quel formalisme adopter ?
Quels sont les formats possibles ?
Quel est le format adapté ?

Media types anyone?

@_dmartin_#hapi
Les media types
Formats sous lesquels des ressources sont représentées
Exprimer le format souhaité (client serveur)→
Informer sur le format retourné (serveur client)→

@_dmartin_#hapi
Les media types courants
Les classiques
• text/html
• application/javascript
• text/css
• image/png
• ...
Les classiques des API
• application/xml
• application/json

@_dmartin_#hapi
Quel rôle pour le media type ?
Un média type pour une API hypermedia doit :
Définir une structure (données + méta données)
Prendre en charge les relations hypermedia
Être ouvert (accessible, évolutif, documenté, ...)

@_dmartin_#hapi
Mauvaise nouvelle...
Mauvaise nouvelle : pas de standard

@_dmartin_#hapi
Bonne nouvelle
Bonne nouvelle : ce n'est pas (trop) grave

@_dmartin_#hapi
Quel media type hypermedia ?
2 approches possibles : créer son format ou en adopter un
1 approche conseillée : en adopter un !
Collection+JSON, HAL, JSON API,
Hydra, JSON-LD, Siren, Uber, NARWHL, ...

@_dmartin_#hapi
Collection+JSON
{ "collection" :
{
"version" : "1.0",
"href" : "http://example.org/friends/",
"links" : [...],
"items" : [...],
"queries" : [...],
"template" : {...},
"errors" : {...}
}
}

@_dmartin_#hapi
Hypermedia Application Language (JSON)
{
"_links": {"self": { "href": "/orders" }, ...}
},
"property1": 14,
"propery2": 20,
"_embedded": {
"embedded_obj1": [{
"_links": {...},
"prop1": 30.00,
"prop2": "USD",
"prop3": "shipped"
}]
}
}
Existe
aussiau
goûtX
M
L

@_dmartin_#hapi
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...

@_dmartin_#hapi
Happy CRUD everyone!
Le paysage actuel
●
Frameworks "CRUD-like API"
●
Souvent orientés "POJO migrateur"
Mais lorsqu'il s'agit des aspects plus intéressants...

@_dmartin_#hapi
Are we doomed Sir ?
Pas de solution clef en main...
… Mais des micro-librairies spécialisées
Spring Hateoas, Siren4j, HALBuilder,
Jersey Declarative Linking, HALselhof…

@_dmartin_#hapi
N'oublions pas l'objectif d'une API Web
Une API Web est créée pour être consommée
Les clients doivent donc comprendre les représentations :
Savoir en extraire les données
Et les méta-données

@_dmartin_#hapi
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...

@_dmartin_#hapi
En synthèse
Aucune obligation...
… Sauf le bon sens ?
Coût et complexité - relatifs - à considérer
MAIS des gains à la clef
Flexibilité
Pérennité
Robustesse

@_dmartin_#hapi
Le mot de la fin...
« Use your brain:
●
Don’t design-by-buzzword
●
Don’t believe everything you read
●
Always keep in mind that change is inevitable »
Roy Fielding - 2008 - A little REST and relaxation

Merci !

Q & A

API Hypermedia - Devoxx 2015

Contenu connexe

Similaire à API Hypermedia - Devoxx 2015

API Hypermedia - Devoxx 2015