3. @_dmartin_#hapi
Linus Torvalds a dit...
“Bad programmers worry about the code. Good programmers worry
about data structures and their relationships.”
7. @_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 !
9. @_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...
10. @_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"}
11. @_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
[...]
13. @_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}
...
14. @_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}
...
15. @_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 !”
16. @_dmartin_#hapi
Le web est hypermedia
Tout est connecté
Navigation intuitive
Découverte des nouveautés
Adaptation au changement
17. @_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
19. @_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 !
20. @_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)
21. @_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...
23. @_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 !
24. @_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
26. @_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+
27. @_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!!!)
29. @_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
30. @_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)
31. @_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"
}
}
33. @_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 !
34. @_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!
38. @_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)→
39. @_dmartin_#hapi
Les media types courants
Les classiques
• text/html
• application/javascript
• text/css
• image/png
• ...
Les classiques des API
• application/xml
• application/json
40. @_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é, ...)
43. @_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, ...
48. @_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...
49. @_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…
50. @_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
51. @_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 !
54. @_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