#Restful really ? ElsassJUG 17 juin 2014

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

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

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"/>
 
 
</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
 
 
HTTP/1.1 200 OK
<appointment>
 
 
 
</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

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

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>
 
 
 
</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
&
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éﬁce que l’on retire de l’idempotence dans une API HTTP ?
- Cela signiﬁe 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

 
 
HTTP/1.1 201 CREATED

Location: slots/1234/appointment
<appointment>
 
 
 
</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.

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

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.

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

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

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

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

 
 
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

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

#Restful really ? ElsassJUG 17 juin 2014

Recomendados

Recomendados

Mais conteúdo relacionado

Destaque

Destaque (18)

Semelhante a #Restful really ? ElsassJUG 17 juin 2014

Semelhante a #Restful really ? ElsassJUG 17 juin 2014 (20)

Mais de Xavier Carpentier

Mais de Xavier Carpentier (6)

#Restful really ? ElsassJUG 17 juin 2014