Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

API Hypermedia - Devoxx 2015

55 views

Published on

Discover the real value of hypermedia relations when used in Web API

Published in: Software
  • Be the first to comment

  • Be the first to like this

API Hypermedia - Devoxx 2015

  1. 1. @_dmartin_#hapi API Hypermedia
  2. 2. @_dmartin_#hapi API Hypermedia twitter.com/_dmartin_ www.ippon.fr Directeur du Pôle Conseil
  3. 3. @_dmartin_#hapi Linus Torvalds a dit... “Bad programmers worry about the code. Good programmers worry about data structures and their relationships.”
  4. 4. Objectifs Comprendre le rôle des relations hypermédia dans les API Web
  5. 5. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi 3...2...1… Go!
  6. 6. @_dmartin_#hapi Définition Qu’appelle t’on API Web ? Une interface... … exploitant les technologies du web … permettant d’interagir avec des données
  7. 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 !
  8. 8. @_dmartin_#hapi Pourquoi ? Pourquoi cet essor ? Simple Rapide Adapté aux use cases actuels A la mode (aussi)
  9. 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. 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. 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 [...]
  12. 12. @_dmartin_#hapi So what? Une API de ce type semble normale… Imaginons maintenant la même chose pour un site web...
  13. 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. 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. 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. 16. @_dmartin_#hapi Le web est hypermedia Tout est connecté Navigation intuitive Découverte des nouveautés Adaptation au changement
  17. 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
  18. 18. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Back to the roots...
  19. 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. 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. 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...
  22. 22. @_dmartin_#hapi RTFM WTF!
  23. 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. 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
  25. 25. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Real life stories...
  26. 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. 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!!!)
  28. 28. @_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/"} ] [...] }
  29. 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. 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. 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" } }
  32. 32. @_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"} ] }
  33. 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. 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!
  35. 35. @_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
  36. 36. @_dmartin_#hapi Quel formalisme adopter ? Quels sont les formats possibles ? Quel est le format adapté ?
  37. 37. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Media types anyone?
  38. 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. 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. 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é, ...)
  41. 41. @_dmartin_#hapi Mauvaise nouvelle... Mauvaise nouvelle : pas de standard
  42. 42. @_dmartin_#hapi Bonne nouvelle Bonne nouvelle : ce n'est pas (trop) grave
  43. 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, ...
  44. 44. @_dmartin_#hapi Collection+JSON { "collection" : { "version" : "1.0", "href" : "http://example.org/friends/", "links" : [...], "items" : [...], "queries" : [...], "template" : {...}, "errors" : {...} } }
  45. 45. @_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
  46. 46. @_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": [ ... ] }
  47. 47. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi In the trenches...
  48. 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. 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. 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. 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 !
  52. 52. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Last lap...
  53. 53. @_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
  54. 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
  55. 55. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Merci !
  56. 56. @YourTwitterHandle@YourTwitterHandle @_dmartin_#hapi Q & A

×