# 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. 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

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é

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

" 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

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 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 …

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

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, accepter la critique, évoluer, faire mieux la prochaine fois

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 !

– 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.

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

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é

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é

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 horaires de disponibilité (slots) de mon médecin à une date donnée via une requête.

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é.

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

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

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)

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é.

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

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 R T 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

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 à travailler avec des ressources individuelles.

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

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

URI1. 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 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é

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 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.

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

idempotent &

safeGET 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

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é.

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, 17 Jun 2014 19:00:00 GMT

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.

H T T P V E R B S

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

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.

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 : Created, 202 : Accepted (asynchrone) 302 : Found 400 : Bad Request 500 : Internal Server Error

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.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.

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

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

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=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).

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 …

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

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

HATEOASHypermedia 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

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

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

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/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

POST /slots/1234 HTTP/1.1

<appointmentRequest> <patient id="xcapetir"/> </appointmentRequest>

1. Pour réserver c’est comme au level 2

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.

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

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.

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 parfait n'existe pas. 2. Rails & Play : pas vraiment facile de faire de la négociation de contenu 3. Spring hateoas, faut toujours maintenir

( 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

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

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.

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

@xcapetir

blog.xavier-carpentier.com

Xavier Carpentier