# R E S T F U L , R E A L LY ?
E L S A S S J U G , 1 7 J U I N 2 0 1 4
@ X C A P E T I R
X AV I E R
C A R P E N T I E R
Developer full stack
d'applications web & mobile Indépendant !
1. Develop...
B U Z Z W O R D
1. ReST c'est vieux mais toujours un buzzword
2. Il est question dans cette présentation non pas du buzzwo...
A R C H I T E C T U R E
1. Lorsque l’on parle de ReST, il s’agit d’architecture, bien sûr pas dans le sens 1er du terme ma...
" O V E R - A R C H I T E C T U R E "
1. Over Complex Architecture
2. Comment éviter de mettre une sur couche inapproprié ...
H Y P E R F L E X I B I L I T Y
1. Au cas où ?
2. no comments
H Y P E R F L E X I B I L I T Y
1. Et là il y aura peut-être une porte un jour, qui sait ?
2. no more comments
C O M P L E X I T Y
1. Au final on se retrouve à gérer de la complexité
2. Les temps de déploiement s’accroisse
3. Les per...
L O S E = > L E A R N
1. Il faut apprendre de ses erreurs
2. Il ne faut pas rester sur un échec, il faut évolué, on peut t...
L E A R N
1. Il faut toujours apprendre, on doit apprendre à apprendre
M AT U R I T Y
1. XP = reconnaitre ses erreurs du passé
2. Il faut réussir à changer, échanger, partager, critiquer, accep...
M O D E R N A R C H I T E C T U R E
1. On rêve d'avoir une architecture moderne
2. Couplage lâche (loose coupling)
3. Légè...
– S T E E V E J O B S
“Simple can be harder than complex: You have to
work hard to get your thinking clean to make it
simp...
A P I S
1. On peut distinguer 3 types d'api
1. Privée : en interne de l’entreprise
2. Partenaire : entre 2 entreprises
3. ...
S TAT E O F A RT
W E B
A P P L I C AT I O N
API
User Interface
1. Voici ce que l’on a l’habitude de voir comme architectur...
B E T T E R A P I
W E B
A P P L I C AT I O N
API
1. Une seule interface
2. Un seule system
3. L’api est conçu dès le dépar...
H T T P A P I 1 0 1
1. B-A BA
2. du niveau zero au meilleur des APIs
L E V E L 0
Supposons que je souhaite prendre un rendez-vous chez mon médecin. Le logiciel de rendez-vous doit d'abord me fournir les ...
POST /appointmentService HTTP/1.1
<openSlotRequest date="2014-06-17" doctor="joeclueless"/>
HTTP/1.1 200 OK
<openSlotList>...
POST /appointmentService HTTP/1.1
<appointmentRequest>


<slot doctor="joeclueless" start="1400" end="1450"/>


<patient i...
HTTP/1.1 200 OK
<appointmentRequestFailure>

!
<slot doctor="joeclueless" start="1400" end="1450"/>


<patient id="xcapeti...
S O A P ( R P C ) P R O B L E M S
tight coupling
1 endpoint
over http
1. il n’y a q’un seul point d’entrée
1. on arrive vi...
S O A P V E R S I O N I N G
Couplage fort entre le client et le serveur et lorsqu’on est amené à faire des modifications l...
S O A P TA S T E
1. Système de type RPC comme SOAP ou même XML-RPC
2. Tout ce qui est sur HTTP n'est pas forcement Rest
3....
H T T P O N O S I M O D E L
A P P L I C AT I O N L AY E R
P R E S E N TAT I O N L AY E R
S E S S I O N L AY E R
T R A N S ...
A P I S TAT I S T I Q U E S - P R O T O C O L
ProgrammableWeb - mars 2014
R E S T V S . S O A P
Google Trends
L E V E L 1
Alors maintenant, plutôt que de faire toutes nos demandes à un seul endpoint d’un service unique, nous commençons à travai...
POST /doctors/joeclueless HTTP/1.1
<openSlotRequest date="2014-06-17"/>
HTTP/1.1 200 OK
<openSlotList>


<slot id="1234" d...
POST /slots/1234 HTTP/1.1
<appointmentRequest>


<patient id="xcapetir"/>


</appointmentRequest>
HTTP/1.1 200 OK
<appoint...
URI
1. Uniform Ressource Identifier
2. Standard ++
3. Simple
… / R E S O U R C E S / …
1. Possibilité de naviguer entre chaque resources …
2. Besoin d’une information sur ce sujet ser...
T H I N K R E S O U R C E
L E V E L 2
1. Jusque là on a utilisé le verbe HTTP POST pour toutes les interactions, mais certaines personnes utilisent GET à la pla...
HTTP/1.1 200 OK
<openSlotList>


<slot id="1234" doctor="joeclueless" start="1400" end="1450"/>


<slot id="5678" doctor="...
idempotent
&
safe
GET est idempotent, càd qu’il peut être appelées plusieurs fois sans problèmes car le système maintient ...
C A C H I N G
1. Le web a était conçut pour être caché
2. HTTP comprend diverses mesures visant à favoriser la mise en cac...
C A C H I N G B U I LT I N
Max-Age
Expires
Conditional GETs (ETags)
C A C H E - C O N T R O L & E X P I R E
HTTP /1.1 200 OK
Cache-Control: public, max-age=3600
HTTP /1.1 200 OK
Expire: Tue,...
POST /slots/1234 HTTP/1.1
<appointmentRequest>


<patient id="xcapetir"/>


</appointmentRequest>
HTTP/1.1 201 CREATED	

L...
H T T P V E R B S
GET : Idempotent & Safe
PUT : Idempotent & Unsafe
POST : No Idempotent & Unsafe
DELETE : Idempotent & Unsafe
OPTIONS : Ide...
HTTP/1.1 409 CONFLICT
<openSlotList>


<slot id="5678" doctor="joeclueless" start="1600" end="1650"/>


</openSlotList>
1....
H T T P S TAT U S C O D E S
1xx : Informations
2xx : Success
3xx : Redirections
4xx : Client errors
5xx : Serveur errors
100 : Continue
200 : OK, 201 ...
T H E S TAT U S F I T S Y O U
Il y a forcement un status code qui doit correspondre à votre situation.
S TAT U S
C O N T E N T T Y P E S
- XML / JSON / TXT / XLS / CSV / PNG / JPEG / …
X M L V S J S O N
ProgrammableWeb - 2013
1. JSON passe devant XML en terme d’API
2. Mais il n’y a pas que XML et JSON
C O N T E N T N E G O T I AT I O N B U I LT I N
C O N T E N T N E G O T I AT I O N
URL Extension
http://domain.com/customer/1234.json
URL Query Parameters
http://domain.c...
V E R S I O N I N G
1. on a vu avec SOAP que des qu’une nouvelle version du serveur était déployé il fallait re-compiler l...
V E R S I O N I N G
URL Versioning
GET /domain.com/api/v1/customer
Custom Header
X-Version: 1.0
Accept Header
Accept: appl...
demo
-> JAX-RS avec Jersey
-> AngularJS
N A I V E M A I L E X A M P L E A P I
GET /mails/
POST /mails/
PATCH /mails/{id}
DELETE /mails/{id}
GET /mails?query=xcape...
L E V E L 2 S U M M A RY
verbs
status code
content-type negotiation
versioning
cache
idempotent & safe
1. On a vu différen...
L E V E L 2 - T I G H T C O U P L I N G
1. Couplage fort, le client doit encore connaitre :
1. url des ressources
2. trans...
R E S T A P I S M U S T B E H Y P E RT E X T- D R I V E N
HATEOAS
Hypermedia As The Engine Of Application State
1. Si vous faite est Restful alors vous devriez connaitre hateoas
2....
HYPERMEDIA
1. On peut parlé d’API hypermedia, c’est plus simple !
2. Système contenant des nœuds liés entre eux par des hy...
D I S C O V E R A B I L I T Y
1. Comme pour le web, on navigue dans de page en page via des liens
2. on découvre l’API par...
L E V E L 3
Levels 3 introduit le control par l'hypermedia.
HTTP/1.1 200 OK
<openSlotList>

<slot id="1234" doctor="joeclueless" start="1400" end="1450">

<link rel="/linkrels/slot/b...
POST /slots/1234 HTTP/1.1
<appointmentRequest>


<patient id="xcapetir"/>


</appointmentRequest>
1. Pour réserver c’est c...
HTTP/1.1 201 CREATED	

Location: slots/1234/appointment
<appointment>



<slot id="1234" doctor="joeclueless" start="1400"...
L O O S E C O U P L I N G
1. L’API force un protocole en avertissant les clients des interaction possible avec ses resourc...
H O R I Z O N TA L S C A L A B I L I T Y
1. Scalabilité verticale : possibilité d’upgrader un serveur (ajout de processeur...
R I C H A R D S O N M AT U R I T Y M O D E L
T O O L S
Ruby On Rails
Spring hateoas
Spray Framework
RestX
Grails
Play Framework
Wasabi
Sinatra
ExpressJS
Swagger
1. L'outil parfa...
( S TA N D A R D ) H Y P E R M E D I A T Y P E
ATOM (XML)
JSON-LD
HAL (JSON)
1. JSON-LD : norme Linked Data pour JSON du w...
R E C O M M E N D AT I O N S
web services / api outside firewall
messaging inside firewall
content negotiation in header
v...
C O N S T R A I N T A N D B E N E F I T S
ReST est devenu un buzzword et les APIs HTTP (web services) sont devenu une trad...
Credits
Caching : https://flic.kr/p/eytW42
Resources : https://flic.kr/p/5uFCiT
Contraintes et bénéfices https://flic.kr/p...
@xcapetir
blog.xavier-carpentier.com
Xavier Carpentier
#Restful really ? ElsassJUG 17 juin 2014
#Restful really ? ElsassJUG 17 juin 2014
#Restful really ? ElsassJUG 17 juin 2014
Prochain SlideShare
Chargement dans…5
×

#Restful really ? ElsassJUG 17 juin 2014

1 750 vues

Publié le

Tout le monde dit faire ou vouloir faire une architecture de type Rest, que cela implique-t-il vraiment ?

Où vous situez-vous sur le "Richardson Maturity Model" ? Votre API est à la fois Hypermedia et JSON, « Are you kidding ? »

Si ce sont des questions qui vous taraudent l'esprit et même vous empêchent de dormir, alors venez écouter ce talk pour avoir des pistes de réflexions, des échanges et peut-être des réponses, qui sait ?

Publié dans : Logiciels

#Restful really ? ElsassJUG 17 juin 2014

  1. 1. # R E S T F U L , R E A L LY ? E L S A S S J U G , 1 7 J U I N 2 0 1 4
  2. 2. @ X C A P E T I R X AV I E R C A R P E N T I E R Developer full stack d'applications web & mobile Indépendant ! 1. Developer full stack application web & mobile 2. Développeur d'API, communication avec partenaires, d'applications web et mobile qui utilisent des APIs 3. J’ai mener une migration d’un style d’architecture RPC vers un style d’architecture ReST chez GreenIvory 4. Scala (Play Framework), Ruby (Ruby On Rails), AngularJS, ReSTful 5. En indépendant depuis 2 mois et demie
  3. 3. B U Z Z W O R D 1. ReST c'est vieux mais toujours un buzzword 2. Il est question dans cette présentation non pas du buzzword Rest mais du style d’architecture défini pas Roy Fiedling 3. Le buzzword du moment c'est Micro-Service 4. Il faut faire attention à comment est utilisé le terme Rest, c’est pas toujours le cas 5. Contrairement à Rest, HTTP manque de popularité et de maitrise par la communauté
  4. 4. A R C H I T E C T U R E 1. Lorsque l’on parle de ReST, il s’agit d’architecture, bien sûr pas dans le sens 1er du terme mais on peut s’en inspirer… 2. Il s’agit d'architecture d’API qui doit répondre aux questions : 1. Déploiement 2. Utilisabilité 3. Performance 4. Durabilité 1. les nouvelles technologies avance à la vitesse de la lumière et par conséquent elles sont vite hasbeen 3. Legacy architectural avec couplage fort, un peu trop ancré au sol
  5. 5. " O V E R - A R C H I T E C T U R E " 1. Over Complex Architecture 2. Comment éviter de mettre une sur couche inapproprié sur notre système 3. Souvent on veut prévoir tout les cas possibles est imaginables et on arrive à ce genre de résultat
  6. 6. H Y P E R F L E X I B I L I T Y 1. Au cas où ? 2. no comments
  7. 7. H Y P E R F L E X I B I L I T Y 1. Et là il y aura peut-être une porte un jour, qui sait ? 2. no more comments
  8. 8. C O M P L E X I T Y 1. Au final on se retrouve à gérer de la complexité 2. Les temps de déploiement s’accroisse 3. Les performances diminues au fil du temps 4. plus communément appelé une "usine à gaz” 5. de multiples branchements 6. des liens à perte de vue 7. des raccord pour camouflé 8. des bidouilles pour que ça marche 9. des patch de bug, patch de patch de bug …
  9. 9. L O S E = > L E A R N 1. Il faut apprendre de ses erreurs 2. Il ne faut pas rester sur un échec, il faut évolué, on peut toujours faire mieux
  10. 10. L E A R N 1. Il faut toujours apprendre, on doit apprendre à apprendre
  11. 11. M AT U R I T Y 1. XP = reconnaitre ses erreurs du passé 2. Il faut réussir à changer, échanger, partager, critiquer, accepter la critique, évoluer, faire mieux la prochaine fois
  12. 12. M O D E R N A R C H I T E C T U R E 1. On rêve d'avoir une architecture moderne 2. Couplage lâche (loose coupling) 3. Légère 4. Scalable à souhait 5. Du repos, de la fluidité, on voudrait que notre architecture soit liquide !
  13. 13. – S T E E V E J O B S “Simple can be harder than complex: You have to work hard to get your thinking clean to make it simple. But it’s worth it in the end because once you get there, you can move mountains.” Faire simple peut être plus difficile que de faire compliqué: Vous devez travailler dure pour avoir une pensé claire pour faire simple. Mais ça vaut la peine car quand vous y arrivez, vous pourrez déplacer des montagnes.
  14. 14. A P I S 1. On peut distinguer 3 types d'api 1. Privée : en interne de l’entreprise 2. Partenaire : entre 2 entreprises 3. Public : accessible par tout le monde ou un subset qui correspond à vos utilisateurs
  15. 15. S TAT E O F A RT W E B A P P L I C AT I O N API User Interface 1. Voici ce que l’on a l’habitude de voir comme architecture d’api aujourd'hui en parallèle de notre application monolithique 2. Deux interfaces 3. Avantages : 1. c’est assez simple 2. il n’y a pas d’autre façon de faire 4. Inconvénient : 1. il y a 2 système à maintenir 2. l’API est habituellement conçut à la fin 3. l’API est limité
  16. 16. B E T T E R A P I W E B A P P L I C AT I O N API 1. Une seule interface 2. Un seule system 3. L’api est conçu dès le départ ! Qu’est-ce qu’il est possible de faire ? Pourquoi maintenant ? 1. Les framework évolue, de plus en plus de choses côté client 2. JavaScript devient un langage viable 3. HTTP a était sous-évalué
  17. 17. H T T P A P I 1 0 1 1. B-A BA 2. du niveau zero au meilleur des APIs
  18. 18. L E V E L 0
  19. 19. Supposons que je souhaite prendre un rendez-vous chez mon médecin. Le logiciel de rendez-vous doit d'abord me fournir les horaires de disponibilité (slots) de mon médecin à une date donnée via une requête.
  20. 20. POST /appointmentService HTTP/1.1 <openSlotRequest date="2014-06-17" doctor="joeclueless"/> HTTP/1.1 200 OK <openSlotList> 
 <slot start="1400" end="1450">
 <doctor id="joeclueless"/>
 </slot> 
 <slot start="1600" end="1650">
 <doctor id="joeclueless"/>
 </slot> 
 </openSlotList> 1. Dans un scénario de niveau 0, l'hôpital va exposer un service par une URL ou je POST un document contenant les détails de ma demande. 2. J'utilise XML ici pour l'exemple, mais le contenu peut effectivement être n'importe quoi: JSON, YAML, paires clé-valeur, ou n'importe quel format personnalisé.
  21. 21. POST /appointmentService HTTP/1.1 <appointmentRequest> 
 <slot doctor="joeclueless" start="1400" end="1450"/> 
 <patient id="xcapetir"/> 
 </appointmentRequest> HTTP/1.1 200 OK <appointment>
 ! <slot doctor="joeclueless" start="1400" end="1450"/> 
 <patient id="xcapetir"/> 
 </appointment> 1. Ma prochaine étape est de réserver un rendez-vous, ce que je peux encore faire en publiant un document via le service 2. Si tout c'est bien passé le service me retourne ma réservation
  22. 22. HTTP/1.1 200 OK <appointmentRequestFailure>
 ! <slot doctor="joeclueless" start="1400" end="1450"/> 
 <patient id="xcapetir"/>
 ! <reason>Slot not available</reason> 
 </appointmentRequestFailure> 1. Par contre si quelqu’un d'autre a réservé avant moi l'horaire pour le même médecin alors le service me renvois une erreur pour m'en informer
  23. 23. S O A P ( R P C ) P R O B L E M S tight coupling 1 endpoint over http 1. il n’y a q’un seul point d’entrée 1. on arrive vite à une soupe sans cohésion (comment découper ?) 2. sur-couche sur http 1. http ne fait que transporter, sans être structurant 2. les erreurs sont dans le payload 3. couplage fort : le client doit connaitre tout du serveur (cf. diapo suivante)
  24. 24. S O A P V E R S I O N I N G Couplage fort entre le client et le serveur et lorsqu’on est amené à faire des modifications le client est tout simplement cassé.
  25. 25. S O A P TA S T E 1. Système de type RPC comme SOAP ou même XML-RPC 2. Tout ce qui est sur HTTP n'est pas forcement Rest 3. Lorsque l'on veut faire un service basé sur Rest, Il faut arrêter de penser RPC (Remote Procedure Call) : SOAP, XML-RPC, etc. 4. A ce niveau là on peut dire qu'il y a une véritable méconnaissance de HTTP
  26. 26. H T T P O N O S I M O D E L A P P L I C AT I O N L AY E R P R E S E N TAT I O N L AY E R S E S S I O N L AY E R T R A N S P O RT L AY E R N E T W O R K L AY E R D ATA L I N K L AY E R P H Y S I C A L L I N K L AY E R 7 6 5 4 3 2 1 H T T P = A P P L I C AT I O N P R O T O C O L
  27. 27. A P I S TAT I S T I Q U E S - P R O T O C O L ProgrammableWeb - mars 2014
  28. 28. R E S T V S . S O A P Google Trends
  29. 29. L E V E L 1
  30. 30. Alors maintenant, plutôt que de faire toutes nos demandes à un seul endpoint d’un service unique, nous commençons à travailler avec des ressources individuelles.
  31. 31. POST /doctors/joeclueless HTTP/1.1 <openSlotRequest date="2014-06-17"/> HTTP/1.1 200 OK <openSlotList> 
 <slot id="1234" doctor="joeclueless" start="1400" end="1450"/> 
 <slot id="5678" doctor="joeclueless" start="1600" end="1650"/> 
 </openSlotList> 1. La requête initial s’execute sur la ressource “doctors" 2. la réponse est presque la même qu’au niveau 0 sauf que maintenant les horaires d’ouverture sont des ressources elles aussi, donc on leur ajoute des identifiants
  32. 32. POST /slots/1234 HTTP/1.1 <appointmentRequest> 
 <patient id="xcapetir"/> 
 </appointmentRequest> HTTP/1.1 200 OK <appointment> 
 <slot id="1234" doctor="joeclueless" start="1400" end="1450"/> 
 <patient id="xcapetir"/> 
 </appointment> 1. On envoi la requête pour prendre un rendez-vous là sur la ressources 2. Et le retour et le même qu'avant
  33. 33. URI 1. Uniform Ressource Identifier 2. Standard ++ 3. Simple
  34. 34. … / R E S O U R C E S / … 1. Possibilité de naviguer entre chaque resources … 2. Besoin d’une information sur ce sujet servez-vous … 3. Comme dans une bibliothèque … 4. Il n’y a plus un seul endpoint … 5. On regroupe les concepts par ressource et on y fait des opérations. 6. On introduit la notion d’identité
  35. 35. T H I N K R E S O U R C E
  36. 36. L E V E L 2
  37. 37. 1. Jusque là on a utilisé le verbe HTTP POST pour toutes les interactions, mais certaines personnes utilisent GET à la place ou en plus 2. Mais ils sont tous les deux utilisés uniquement comme mécanismes de tunnel via HTTP 3. Nous allons voir qu’on peut leur donner plus de sens à ces verbes HTTP ! Le level 2 quant à lui utilise les verbes HTTP.
  38. 38. HTTP/1.1 200 OK <openSlotList> 
 <slot id="1234" doctor="joeclueless" start="1400" end="1450"/> 
 <slot id="5678" doctor="joeclueless" start="1600" end="1650"/> 
 </openSlotList> GET /doctors/joeclueless/slots?date=20140617&status=open HTTP/1.1 Host: elsasshope.nhc.fr 1. Pour avoir la liste des horaires de disponibilité on fait un GET 2. Et la réponse est la même qu'avant
  39. 39. idempotent & safe GET est idempotent, càd qu’il peut être appelées plusieurs fois sans problèmes car le système maintient le même état après une ou plusieurs invocations : toutes les variables gardent la valeur qu'elles avaient après la première invocation. Exemple : 1. Rechercher le nom d'un client dans une base de données est typiquement idempotent, car cela ne change pas la base de données. 2. Le tri d'une liste d'éléments est une procédure idempotente. Une fois la liste triée, le fait de la trier à nouveau ne changera pas l'ordre des éléments ; la liste ne sera donc pas modifiée. 3. Passer une commande n'est pas idempotent, car plusieurs invocations résulteront en plusieurs commandes. Annuler une commande au contraire est idempotent car la commande reste annulée quel que soit le nombre d’invocations. ! Est-ce que quelqu’un a une idée du bénéfice que l’on retire de l’idempotence dans une API HTTP ? - Cela signifie que l’on peut cacher le GET
  40. 40. C A C H I N G 1. Le web a était conçut pour être caché 2. HTTP comprend diverses mesures visant à favoriser la mise en cache, qui peuvent être utilisés par tous les participants à la communication. C’est en suivant les contraintes d'HTTP que nous sommes en mesure de tirer parti de cette capacité.
  41. 41. C A C H I N G B U I LT I N Max-Age Expires Conditional GETs (ETags)
  42. 42. C A C H E - C O N T R O L & E X P I R E HTTP /1.1 200 OK Cache-Control: public, max-age=3600 HTTP /1.1 200 OK Expire: Tue, 17 Jun 2014 19:00:00 GMT
  43. 43. POST /slots/1234 HTTP/1.1 <appointmentRequest> 
 <patient id="xcapetir"/> 
 </appointmentRequest> HTTP/1.1 201 CREATED Location: slots/1234/appointment <appointment> 
 <slot id="1234" doctor="joeclueless" start="1400" end="1450"/> 
 <patient id="xcapetir"/> 
 </appointment> 1. Pour réserver on a besoin d’un verbe qui change l’état, POST ou PUT. Mais pour faire un simple copier coller, on va faire comme tout à l’heure, on utilise un POST 2. Le retour du serveur est sensiblement différent car il indique au client que la ressources est bien créé et que pour y accéder on peut utiliser l’url défini dans le header “Location”, on peut donc faire un GET directement sur cette URI. Ca signifie au client qu’a l’avenir cette reservation sera identifiée de cette façon. Cependant la réponse contient également dans le payload une représentation de la réservation, ce qui permet de sauvé un aller retour serveur et de pouvoir utiliser les données immédiatement si on en a besoin.
  44. 44. H T T P V E R B S
  45. 45. GET : Idempotent & Safe PUT : Idempotent & Unsafe POST : No Idempotent & Unsafe DELETE : Idempotent & Unsafe OPTIONS : Idempotent & Safe HEAD : Idempotent & Safe PATCH : No Idempotent & Unsafe 1. GET : cacheable 2. PUT : pour créer ou modifier 3. POST : pour créer et modifier, mais pas pour rechercher … 4. HEAD : comme un GET sans le payload (ex: connaitre la taille, le type de contenu, etc.) 5. PATCH : pour faire une mise à jours d’une sous partie du document 6. OPTIONS : pour connaitre les verbes autorisés sur une resources 1. Toutes les ressources n’authorise pas toute les méthode (405 Method Not Allowed) 2. Permet de restreindre les droits sur une ressources, par exemple faire de la lecture seule ou empêcher la suppression
  46. 46. HTTP/1.1 409 CONFLICT <openSlotList> 
 <slot id="5678" doctor="joeclueless" start="1600" end="1650"/> 
 </openSlotList> 1. Quelqu’un à prit un rendez-vous avant moi… erreur… 2. Par contre, contrairement au niveau précédent, lorsqu’il y a une erreur on s’appui sur HTTP pour trouver le code qui correspond à notre erreur. C'est au concepteur de protocole de décider quels sont les codes à utiliser, mais il devrait y avoir une réponse non 200 si une erreur surgit.
  47. 47. H T T P S TAT U S C O D E S
  48. 48. 1xx : Informations 2xx : Success 3xx : Redirections 4xx : Client errors 5xx : Serveur errors 100 : Continue 200 : OK, 201 : Created, 202 : Accepted (asynchrone) 302 : Found 400 : Bad Request 500 : Internal Server Error
  49. 49. T H E S TAT U S F I T S Y O U Il y a forcement un status code qui doit correspondre à votre situation.
  50. 50. S TAT U S
  51. 51. C O N T E N T T Y P E S - XML / JSON / TXT / XLS / CSV / PNG / JPEG / …
  52. 52. X M L V S J S O N ProgrammableWeb - 2013 1. JSON passe devant XML en terme d’API 2. Mais il n’y a pas que XML et JSON
  53. 53. C O N T E N T N E G O T I AT I O N B U I LT I N
  54. 54. C O N T E N T N E G O T I AT I O N URL Extension http://domain.com/customer/1234.json URL Query Parameters http://domain.com/customer/1234?format=json Accept Headers Accept: application/json; q=0.7, application/xml; q=0.2 Accept-Language: fr, en-us; q=0.9 1. ajout du format en extension 2. format en query 3. format dans le content-type 4. On peut faire notre marché, on voudrait une représentation dans un certain type de contenu alors il faut le spécifier dans le header accept.
  55. 55. V E R S I O N I N G 1. on a vu avec SOAP que des qu’une nouvelle version du serveur était déployé il fallait re-compiler le client. 2. Avec HTTP rien ne nous oblige de faire ça, alors il y a différent moyen de versioner 3. L’important dans un système de version n’est pas tant de pouvoir créer une nouvelle version mais surtout de conserver les anciennes versions
  56. 56. V E R S I O N I N G URL Versioning GET /domain.com/api/v1/customer Custom Header X-Version: 1.0 Accept Header Accept: application/vnd.mytype.v2+json Accept: application/json;v=2 1. version dans l'url 2. version dans un custom header 3. version dans le content-type (avec 2 variantes) 4. Je recommande la version dans le header accept, pas obligé de le prévoir dès le départ
  57. 57. demo -> JAX-RS avec Jersey -> AngularJS
  58. 58. N A I V E M A I L E X A M P L E A P I GET /mails/ POST /mails/ PATCH /mails/{id} DELETE /mails/{id} GET /mails?query=xcapetir GET /mails?start=0&end=20 1. GET /mails/ => pour récupérer une liste simple des mails dans la boite mail (dates, objets, expéditeurs, destinataires) 2. POST /mails/ => le serveur récupère ton mail du request body et retourne l'URI de la ressources créé (header Location et body) avec un body contenant l'information du non envoi du mail (là juste pour la sauvegarde sans envoi) 3. PATCH /mails/{id} => mise à jour partiel de l'information d'envois => c'est là qu'on envois le message via SMTP, .... 4. DELETE /mails/{id} => suppression d'un mail 5. GET /mails/?query=xcapetir => recherche (filtre) fulltext de la query string “xcapetir", la pagination (start=0, size=10).
  59. 59. L E V E L 2 S U M M A RY verbs status code content-type negotiation versioning cache idempotent & safe 1. On a vu différente chose qui nous on permit de construire un model pseudo CRUD (ne dites que j’ai dit que REST = CRUD, c’est pas vrai ;) ) 2. Il y a tout de même encore un problème …
  60. 60. L E V E L 2 - T I G H T C O U P L I N G 1. Couplage fort, le client doit encore connaitre : 1. url des ressources 2. transitions 3. workflows
  61. 61. R E S T A P I S M U S T B E H Y P E RT E X T- D R I V E N
  62. 62. HATEOAS Hypermedia As The Engine Of Application State 1. Si vous faite est Restful alors vous devriez connaitre hateoas 2. Hypermedia As Engine Of Application State 3. Le moteur de l'état de l'application
  63. 63. HYPERMEDIA 1. On peut parlé d’API hypermedia, c’est plus simple ! 2. Système contenant des nœuds liés entre eux par des hyperliens : passer automatiquement d'un nœud à un autre 3. hypertexte a trouvé sa plus grande réalisation dans le World Wide Web
  64. 64. D I S C O V E R A B I L I T Y 1. Comme pour le web, on navigue dans de page en page via des liens 2. on découvre l’API par l’API 3. auto descriptive, auto découverte, auto-documentation
  65. 65. L E V E L 3
  66. 66. Levels 3 introduit le control par l'hypermedia.
  67. 67. HTTP/1.1 200 OK <openSlotList>
 <slot id="1234" doctor="joeclueless" start="1400" end="1450">
 <link rel="/linkrels/slot/book"
 uri="/slots/1234"/>
 </slot>
 <slot id="5678" doctor="joeclueless" start="1600" end="1650">
 <link rel="/linkrels/slot/book"
 uri="/slots/5678"/>
 </slot>
 </openSlotList> GET /doctors/joeclueless/slots?date=20140617&status=open HTTP/1.1 Host: elsasshope.nhc.fr 1. Chaque disponibilité dispose d'un élément de liaison qui contient une URI pour nous dire comment réserver un rendez-vous 2. Le contrôle hypermédia = l’API nous dit ce qu’on peut faire maintenant et il nous fournit l’URI pour le faire. Sans savoir à l’avance comment faire nous pouvons réserver un rendez-vous
  68. 68. POST /slots/1234 HTTP/1.1 <appointmentRequest> 
 <patient id="xcapetir"/> 
 </appointmentRequest> 1. Pour réserver c’est comme au level 2
  69. 69. HTTP/1.1 201 CREATED Location: slots/1234/appointment <appointment>
 
 <slot id="1234" doctor="joeclueless" start="1400" end="1450"/>
 
 <patient id="xcapetir"/>
 
 <link rel="/linkrels/appointment/cancel"
 uri="/slots/1234/appointment"/>
 
 <link rel="/linkrels/appointment/addTest"
 uri="/slots/1234/appointment/tests"/>
 
 <link rel="self"
 uri="/slots/1234/appointment"/>
 
 <link rel="/linkrels/appointment/changeTime"
 uri=“/doctors/joeclueless/slots?date=20100104&status=open"/>
 
 <link rel="/linkrels/appointment/updateContactInfo"
 uri="/patients/xcapetir/contactInfo"/>
 
 <link rel="/linkrels/help"
 uri="/help/appointment"/>
 
 </appointment> 1. Un avantage évident du contrôle par hypermedia est que le serveur peut changer son schéma d’url sans casser le client, tant que le client cherche le lien “addTests" le serveur peut changer tant qu’il veut les point d’entrée initiaux 2. Un autre avantage c’est que le développeur front peut se documenter sur l’API uniquement en lisant les relations et les liens. Quand on sait que personne n’aime écrire de la documentation c’est quand même sympa (et c’est un gain de temps) 3. De plus les développeurs back-end (serveur) peuvent annoncer de nouvelle capacité en ajoutant à tout moment de nouveau lien dans les réponses. Si les développeurs front-end surveillent régulièrement les liens ils peuvent facilement ajouter cette nouvelle capacité à leur client juste en allant explorer de façon plus poussé. 4. Il n’y a pas de norme absolu quant à la façon de représenter les contrôles hypermédia. Ce qui est fait ici suit la recommandation ATOM (RFC 4287) 1. utilisation d’une balise link 2. attribut uri cible 3. attribut rel pour décrire le genre de relation 5. SELF est une relation bien connu qui fait référence à la ressources elle même.
  70. 70. L O O S E C O U P L I N G 1. L’API force un protocole en avertissant les clients des interaction possible avec ses resources 2. Reduction du couplage entre le serveur et le client 3. L’API peut évoluer sans se soucier de ceux qui en sont consommateur
  71. 71. H O R I Z O N TA L S C A L A B I L I T Y 1. Scalabilité verticale : possibilité d’upgrader un serveur (ajout de processeurs, RAM, disques…). 2. Scalabilité horizontale : possibilité d’ajouter des serveurs d’un type donné. Par exemple : ajout possible de serveurs d'application web avec répartition de charge.
  72. 72. R I C H A R D S O N M AT U R I T Y M O D E L
  73. 73. T O O L S
  74. 74. Ruby On Rails Spring hateoas Spray Framework RestX Grails Play Framework Wasabi Sinatra ExpressJS Swagger 1. L'outil parfait n'existe pas. 2. Rails & Play : pas vraiment facile de faire de la négociation de contenu 3. Spring hateoas, faut toujours maintenir
  75. 75. ( S TA N D A R D ) H Y P E R M E D I A T Y P E ATOM (XML) JSON-LD HAL (JSON) 1. JSON-LD : norme Linked Data pour JSON du w3c 2. HAL utilisé par Amazon AppStream (Amazon se fie peu au standard) 3. Collection+JSON (Mike Amundsen) 4. Siren
  76. 76. R E C O M M E N D AT I O N S web services / api outside firewall messaging inside firewall content negotiation in header version in header HTTP != CRUD 1. ne pas utiliser Rest si vous avez besoin de 100ms de latence 2. utiliser la négociation de contenu dans le header 3. utiliser la version dans le header
  77. 77. C O N S T R A I N T A N D B E N E F I T S ReST est devenu un buzzword et les APIs HTTP (web services) sont devenu une tradition dans nos systèmes d'information. Mais les deux choses, d'un côté un style d'architecture et de l'autre un protocole ne sont pas forcément identique, au détriment de la qualité, de la beauté et des performances de nos APIs. Malheureusement, des protocoles orientés RPC (Remote Procedure Call) ont déformés notre façon de penser nos services et on construit leur propre monde au dessus de HTTP. On doit donc faire un effort pour penser autrement, pour penser ressource et devenir ReSTful. ReST défini un certain nombre de contraintes parfois difficiles ou couteuses à mettre en oeuvre mais qui garantissent un bénéfice que les grands du web comme Google, Facebook et Amazon ont suent utiliser. Il faut améliorer notre compréhension de HTTP et sa toute suffisance pour créer des applications et des APIs.
  78. 78. Credits Caching : https://flic.kr/p/eytW42 Resources : https://flic.kr/p/5uFCiT Contraintes et bénéfices https://flic.kr/p/jpFxCU Content-types : https://flic.kr/p/dDRt7a Old man : https://flic.kr/p/iuXxoa Trains : https://flic.kr/p/76iUay Verbes : https://flic.kr/p/Z9Z8u Soap taste : https://flic.kr/p/7D83Gy Learn : https://flic.kr/p/3raqY Complexity : https://flic.kr/p/cFM3cd Tools : https://flic.kr/p/4CPscx Buzzword : https://flic.kr/p/4VCB56 Status code fit : https://flic.kr/p/3391Mh Negociation : https://flic.kr/p/aGKB3n Loose coupling : https://flic.kr/p/54FKyC RMM : http://martinfowler.com/articles/richardsonMaturityModel.html Scalabilité : https://flic.kr/p/aCiaWW
  79. 79. @xcapetir blog.xavier-carpentier.com Xavier Carpentier

×