RAML une autre façon de concevoir vos APIs RESTful - Devoxx France 2016 - Tools-in-Action

RAML est le langage de description des API RESTful qui monte et qui gagne à être connu. Ce langage favorise la réutilisation : Don't Repeat Yourself ! Avec le nombre d'APIs qui augmente constamment, RAML est donc le bienvenu.

Nous verrons donc comment décrire très simplement et rapidement une API, factoriser la description et générer une description interactive à publier en ligne !

Transcript

1. RAML une autre façon de RAML une autre façon de concevoir vos APIs RESTful concevoir vos APIs RESTful Sébastien LECACHEUR Jeudi 21 avril - Neuilly 252 AB - 18h55 @slecache 1 #DevoxxFR #RAML
2. #DevoxxFR #RAML Agenda Agenda Contexte RAML Bilan Démos Perspectives 2
3. Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0 3 #DevoxxFR #RAML
4. T T N N T T Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0 3 #DevoxxFR #RAML
5. T Types ypes & & T Traits raits Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0 3 #DevoxxFR #RAML
6. #DevoxxFR #RAML Le contexte Le contexte Pour nos APIs, nous cherchions... Pour nos APIs, nous cherchions... 4
7. #DevoxxFR #RAML Le contexte Le contexte Pour nos APIs, nous cherchions... Pour nos APIs, nous cherchions... Une documentation documentation pour les utilisateurs internes et externes, 4
8. #DevoxxFR #RAML Le contexte Le contexte Pour nos APIs, nous cherchions... Pour nos APIs, nous cherchions... Une documentation documentation pour les utilisateurs internes et externes, rédigée avant l'implémentation pour une approche contract first contract first, 4
9. #DevoxxFR #RAML Le contexte Le contexte Pour nos APIs, nous cherchions... Pour nos APIs, nous cherchions... Une documentation documentation pour les utilisateurs internes et externes, rédigée avant l'implémentation pour une approche contract first contract first, gérée comme du code comme du code source, 4
10. #DevoxxFR #RAML Le contexte Le contexte Pour nos APIs, nous cherchions... Pour nos APIs, nous cherchions... Une documentation documentation pour les utilisateurs internes et externes, rédigée avant l'implémentation pour une approche contract first contract first, gérée comme du code comme du code source, et lisible lisible par des humains. 4
11. Qui a dit Qui a dit MS Word ? MS Word ? by Ryan McGuire under CC0 1.0 5 #DevoxxFR #RAML
12. #DevoxxFR #RAML R RESTful ESTful A API PI M Modeling odeling L Language anguage YAML 2013 Mulesoft, AngularJS, PayPal Spécifications sur Vmware, Cisco, Spotify, etc... Restlet, Amazon API Gateway http://raml.org Github 6 . 1
13. #DevoxxFR #RAML RAML - Objectifs RAML - Objectifs With RAML you can truly With RAML you can truly , , , , , , , and , and your API all with one spec. your API all with one spec. design design build build test test document document share share 6 . 2
14. #DevoxxFR #RAML RAML - Spec Driven Development RAML - Spec Driven Development 6 . 3
15. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... 7
16. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... Une documentation documentation pour tous les utilisateurs et développeurs, 7
17. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... Une documentation documentation pour tous les utilisateurs et développeurs, générée automatiquement à partir de code code YAML qui est lisible lisible par des humains et versionné sur Git. 7
18. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... Une documentation documentation pour tous les utilisateurs et développeurs, générée automatiquement à partir de code code YAML qui est lisible lisible par des humains et versionné sur Git. Mais aussi... Mais aussi... 7
19. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... Une documentation documentation pour tous les utilisateurs et développeurs, générée automatiquement à partir de code code YAML qui est lisible lisible par des humains et versionné sur Git. Mais aussi... Mais aussi... Un outil et une méthode de conception conception des APIs, 7
20. #DevoxxFR #RAML Le bilan Le bilan Avec Avec RAML RAML, nous avons obtenu... , nous avons obtenu... Une documentation documentation pour tous les utilisateurs et développeurs, générée automatiquement à partir de code code YAML qui est lisible lisible par des humains et versionné sur Git. Mais aussi... Mais aussi... Un outil et une méthode de conception conception des APIs, ainsi qu'un try it out try it out ! 7
21. #DevoxxFR #RAML 8
22. #DevoxxFR #RAML une ressource /albums: 8
23. #DevoxxFR #RAML une ressource /albums: des verbes get: post: 8
24. #DevoxxFR #RAML une ressource /albums: des verbes get: post: un identifiant /albums/{id}: patch: get: 8
25. #DevoxxFR #RAML une ressource /albums: des verbes get: post: un identifiant /albums/{id}: patch: get: un format de représentation response: 200: body: application/json: example: | {"id":1, title":"Nevermind"} 8
26. #DevoxxFR #RAML une ressource /albums: des verbes get: post: un identifiant /albums/{id}: patch: get: un format de représentation response: 200: body: application/json: example: | {"id":1, title":"Nevermind"} Votre premier RAML ! Votre premier RAML ! 8
27. Assez parlé ! Assez parlé ! Code by Crusher95 under CC BY-SA 4.0 9 . 1 #DevoxxFR #RAML
28. #DevoxxFR #RAML Démo Démo édition - API Workbench + 1ière API documentation raml2html api:Console mocks - osprey-mock-service tests - abao top-down en Java Maven/JAX-RS : génération des sources Maven/JAX-RS : serveur Jersey 9 . 2
29. D Don't on't R Repeat epeat Y Yourself ourself Egyptian Clones by Guillaume DELEBARRE under CC BY-NC-ND 2.0 10 #DevoxxFR #RAML
30. Explosion by mikegi under CC0 1.0 11 #DevoxxFR #RAML
31. T T N N T T Explosion by mikegi under CC0 1.0 11 #DevoxxFR #RAML
32. T Types ypes & & T Traits raits Explosion by mikegi under CC0 1.0 11 #DevoxxFR #RAML
33. Take away Take away by Vee O under CC0 1.0 12 . 1 #DevoxxFR #RAML
34. #DevoxxFR #RAML Aller plus loin Aller plus loin RAML 1.0 : data types, annotations, overlays, libraries, security schemes, etc... Parseurs RAML Image Docker $ docker run slecache/api-console $ docker run slecache/api-console:raml-1.0 https://github.com/raml-apis http://api.yaas.io/patterns/ 12 . 2
35. #DevoxxFR #RAML Ce qu'il faut retenir Ce qu'il faut retenir contract first contract first : cycle rapide de conception mais impose de la rigueur une documentation très claire Types Types & Traits Traits Undisturbed REST 12 . 3
36. A vous de jouer et concevoir vos APIs... That's all folks by Warner Bros. under public domain 13 #DevoxxFR #RAML