API Hypermedia - Devoxx 2015

Sample presentation

API Hypermedia

API Hypermedia

twitter.com/_dmartin_

www.ippon.frDirecteur du Ple Conseil

Linus Torvalds a dit...

Bad programmers worry about the code. Good programmers worry about data structures and their relationships.

Objectifs

Comprendre le rle des relations hypermdiadans les API Web

3...2...1 Go!

Dfinition

Quappelle ton API Web ?

Une interface... exploitant les technologies du web permettant dinteragir avec des donnes

Here, There and Everywhere!

On parle des API partout !Phnomne de mode ?ou tout simplement adapt aux usages ?

Qui n'a pas son API en 2015 ?Toutes les startups cools ont leur APILes grands du net ont leur APIMme les institutions ouvrent leurs API !

Pourquoi?

Pourquoi cet essor ?

Simple

Rapide

Adapt aux use cases actuels

A la mode (aussi)

As easy as ABC...

Crer son API semble simple :

Choisir un framework (spcialis ou gnraliste)Dfinir quelques ressourcesEcrire un peu de conf...

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, 401Unauthorized, 403 Forbidden, 404 Not Found, ...

{"user_id":1,"name":"Chris Rivers", "nickname":"chris"}

Avec une jolie doc

GET /users{?page}Retourne les utilisateurs 10 par 10 (voir Pagination).Exemple de rponse :[{"id":"23423423","firstname":"Roy","lastname":"Trenneman"}, {...}]

Pagination :Paramtre : page (optionnel)Valeur : un entier positif dcrivant le numro de la page afficher[...]

So what?

Une API de ce type semble normale

Imaginons maintenant la mme chose pour un site web...

Facebook sans relation hypermdia

Notice de Facebook :

Pour accder aux profils individuels de vos amis, compltez cette adresse :

https://www.facebook.com/{usernickname}

...

Google sans relation hypermdia

Notice de Google :

Pour effectuer une recherche, compltez cette adresse :https://www.google.fr/search?q={mots_clef}

Pagination :Chaque page contient 10 documents. Pour naviguer parmi l'ensemble des rponses, utilisez cette adresse :https://www.google.fr/search?q={mots_clef}&start={item_nb}...

Le web sans relation hypermdia

Le speaker : Avez-vous envie d'apprendre crire les URL spcifiques de chaque site ?!?La salle : Non !Le speaker : Et pourquoi ?La salle : Inutile : il suffit decliquer sur les liens proposs !

Le web est hypermedia

Tout est connectNavigation intuitiveDcouverte des nouveautsAdaptation au changement

Le web sans relation hypermdia

Cot client (browser)

Votre navigateur sait suivre des liens TOUT SEULIl comprend ce que chacun lui apporte TOUT SEUL

A t'il besoin d'une quelconque intelligence? NON

Back to the roots...

REST

Style darchitecture aussi mconnu que connuPourtant introduit en 2000 (o tiez-vous il y a 15 ans ?)Concepts pour architectures distribues prennesContraintes respecter, certaines optionnelles, d'autres obligatoires comme le fait de reposer sur les relations hypermdia !

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)

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

RTFM WTF!

Pourquoi une API hypermedia ?

Sans relation hypermdia :Hardcoder les chemins

Connatre les flows

Client limit, trs coupl l'API Impossible d'voluer sans risque!

Pourquoi une API hypermedia ?

Avec relation hypermdia :Dcouvrir les relations et leur sens

Consommer au lieu de construire

Dtecter les variations, informer et sadapter

Client plus robustevolutions plus simples introduire

Real life stories...

GET /users/1234{"name":"Roy Trenneman"}L'API hypermedia illustre

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

+

Premier constat

Premier constat

Pas besoin dun client complexe L'API dispose de souplesse pour voluer

Le client consomme ce dont il a besoinIl ne cre pas les URLIl peut avertir de nouveauts non comprises (new features!!!)

{ [...] "links": [{"rel":"v1:user", "href":"/toto/userZ"}] [...]}L'API hypermedia illustre

{ [...] "links": [ {"rel":"v1:user","href":"/toto/userZ","deprecated":"true"}, {"rel":"v2:user","href":"/new_users/"} ] [...]}

Cration d'une ressource

POST /people{"name" : "Jen Barber"}

HTTP/1.1 201 CreatedContent-Location: http://[...]/abcde

{representation}

201 + Content-Location + reprsentation

Le header Link (RFC5988)

Link: ; rel="next", ; rel="last"Header Link: Approche alternative pour exprimer des relations

Exemple GitHub API :

A noter: Link-Template (draft IETF)

La reprsentation polyforme

{ "inStock": { "value":"true", "type": "embedded" }}Embedded & Remote

Le client comprend les notions embedded et remote Il s'adapte aux rponses L'API choisit le mode optimal (User-Agent, ...)

{ "inStock": { "value":"http://[...]/prodId/avail", "type": "remote" }}

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"} ]}

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 paramtres (maintenance, ...)

Et construit un flow adapt

PAS le client !

Mais... ne serait-ce pas ?

Permettre de modifier ltat de lapplication en exposant les transitions possibles sous forme de liens hypermdia

HATEOAS!

Buzzword detected!

Reprsentation plus complexe

Constat: Reprsentation enrichie

No more POJO migrateur Modle simpliste : rserv des usages limits

Il faut:Transporter des donnes

Transporter des mtadonnes

Quel formalisme adopter?

Quels sont les formats possibles?Quel est le format adapt?

Media types anyone?

Les media types

Formats sous lesquels des ressources sont reprsentes

Exprimer le format souhait (client serveur)

Informer sur le format retourn (serveur client)

Les media types courants

Les classiquestext/html

application/javascript

text/css

image/png

...

Les classiques des APIapplication/xml

application/json

Quel rle pour le media type ?

Un mdia type pour une API hypermedia doit :

Dfinir une structure (donnes + mta donnes)

Prendre en charge les relations hypermedia

tre ouvert (accessible, volutif, document, ...)

Mauvaise nouvelle...

Mauvaise nouvelle : pas de standard

Bonne nouvelle

Bonne nouvelle : ce n'est pas (trop) grave

Quel media type hypermedia?

2 approches possibles: crer son format ou en adopter un1 approche conseille: en adopter un!

Collection+JSON, HAL, JSON API,Hydra, JSON-LD, Siren, Uber, NARWHL, ...

Collection+JSON

{ "collection" : { "version" : "1.0", "href" : "http://example.org/friends/", "links" : [...], "items" : [...], "queries" : [...], "template" : {...}, "errors" : {...} } }

Hypermedia Application Language (JSON)

{ "_links": {"self": { "href": "/orders" }, ...} }, "property1": 14, "propery2": 20, "_embedded": { "embedded_obj1": [{ "_links": {...}, "prop1": 30.00, "prop2": "USD", "prop3": "shipped" }] }}Existe aussi au got XML

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": [ ... ]}

In the trenches...

Happy CRUD everyone!

Le paysage actuel

Frameworks "CRUD-like API"

Souvent orients "POJO migrateur"

Mais lorsqu'il s'agit des aspects plus intressants...

Are we doomed Sir?

Pas de solution clef en main...

Mais des micro-librairies spcialises

Spring Hateoas, Siren4j, HALBuilder,Jersey Declarative Linking, HALselhof

N'oublions pas l'objectif d'une API Web

Une API Web est cre pour tre consomme

Les clients doivent donc comprendre les reprsentations:Savoir en extraire les donnes

Et les mta-donnes

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 !

Last lap...

En synthse

Aucune obligation... Sauf le bon sens ?Cot et complexit - relatifs - considrer

MAIS des gains la clefFlexibilit

Prennit

Robustesse

Le mot de la fin...

Use your brain:Dont design-by-buzzword

Dont believe everything you read

Always keep in mind that change is inevitable

Roy Fielding - 2008 - A little REST and relaxation

Merci!

Q & A

@YourTwitterHandle#YourSessionHashtag

@_dmartin_#hapiClick to edit the title text formatTexte du titre


@_dmartin_#hapiClick to edit the title text formatTexte du titre

Click to edit the outline text formatSecond Outline LevelThird Outline LevelFourth Outline LevelFifth Outline LevelSixth Outline LevelSeventh Outline LevelTexte niveau1Texte niveau2Texte niveau3Texte niveau4

Texte niveau 5

@_dmartin_#hapi

Click to edit the title text formatTexte du titre


Texte niveau 5





@YourTwitterHandle@YourTwitterHandle

@_dmartin_#hapi

@_dmartin_#hapi



Texte niveau 5



@_dmartin_#hapi



@YourTwitterHandle@YourTwitterHandle

@_dmartin_#hapi




Texte niveau 5

@_dmartin_#hapi

API Hypermedia - Devoxx 2015

Software

Transcript of API Hypermedia - Devoxx 2015