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
   

   View Slide

2. #DevoxxFR #RAML
   Agenda
   Agenda
   Contexte
   RAML
   Bilan
   Démos
   Perspectives
   2
   

   View Slide

3. Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0
   3
   #DevoxxFR #RAML
   

   View Slide

4. T
   T
   N
   N
   T
   T
   Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0
   3
   #DevoxxFR #RAML
   

   View Slide

5. T
   Types
   ypes
   &
   &
   T
   Traits
   raits
   Dynamite Pin by Kenny_lex under CC BY-NC-SA 2.0
   3
   #DevoxxFR #RAML
   

   View Slide

6. #DevoxxFR #RAML
   Le contexte
   Le contexte
   Pour nos APIs, nous cherchions...
   Pour nos APIs, nous cherchions...
   4
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
    

    View Slide

11. Qui a dit
    Qui a dit
    MS Word ?
    MS Word ?
    by Ryan McGuire under CC0 1.0
    5
    #DevoxxFR #RAML
    

    View Slide

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
    

    View Slide

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
    

    View Slide

14. #DevoxxFR #RAML
    RAML - Spec Driven Development
    RAML - Spec Driven Development
    6 . 3
    

    View Slide

15. #DevoxxFR #RAML
    Le bilan
    Le bilan
    Avec
    Avec RAML
    RAML, nous avons obtenu...
    , nous avons obtenu...
    7
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

21. #DevoxxFR #RAML 8
    

    View Slide

22. #DevoxxFR #RAML
    une ressource /albums:
    8
    

    View Slide

23. #DevoxxFR #RAML
    une ressource /albums:
    des verbes get:
    post:
    8
    

    View Slide

24. #DevoxxFR #RAML
    une ressource /albums:
    des verbes get:
    post:
    un identifiant /albums/{id}:
    patch:
    get:
    8
    

    View Slide

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
    

    View Slide

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
    

    View Slide

27. Assez parlé !
    Assez parlé !
    Code by Crusher95 under CC BY-SA 4.0
    9 . 1
    #DevoxxFR #RAML
    

    View Slide

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
    

    View Slide

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
    

    View Slide

30. Explosion by mikegi under CC0 1.0
    11
    #DevoxxFR #RAML
    

    View Slide

31. T
    T
    N
    N
    T
    T
    Explosion by mikegi under CC0 1.0
    11
    #DevoxxFR #RAML
    

    View Slide

32. T
    Types
    ypes
    &
    &
    T
    Traits
    raits
    Explosion by mikegi under CC0 1.0
    11
    #DevoxxFR #RAML
    

    View Slide

33. Take away
    Take away
    by Vee O under CC0 1.0
    12 . 1
    #DevoxxFR #RAML
    

    View Slide

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
    

    View Slide

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
    

    View Slide

36. A vous de jouer et concevoir vos APIs...
    That's all folks by Warner Bros. under public domain
    13
    #DevoxxFR #RAML
    

    View Slide