Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Preparing for the future of API Description Languages

Preparing for the future of API Description Languages

API Description languages come and go. At Apiary we’ve supported nearly 4 formats without significantly changing our code base. In this session we will talk about how we’ve prepared Apiary for the future of API Description languages. We will cover the evolving domain of API Description, including the new features and concepts introduced in OAS3.

Kyle Fuller

May 16, 2018
Tweet

More Decks by Kyle Fuller

Other Decks in Technology

Transcript

  1. Preparing for the future of API
    Description Languages
    @kylefuller
    © Oracle Corpora,on UK Limited, 2018 1

    View full-size slide

  2. Preparing for the future of API
    Description Languages
    @kylefuller
    © Oracle Corpora,on UK Limited, 2018 2

    View full-size slide

  3. © Oracle Corpora,on UK Limited, 2018 3

    View full-size slide

  4. Agenda
    • Evolu'on of formats in Apiary
    • How we tackled suppor'ng mul'ple formats
    • Our plan for suppor'ng OAS 3
    • Differences between Swagger 2 and OAS 3
    © Oracle Corpora,on UK Limited, 2018 4

    View full-size slide

  5. Apiary Blueprint
    2012 - 2014
    © Oracle Corpora,on UK Limited, 2018 5

    View full-size slide

  6. API Blueprint 1
    2014 - Present
    1 h$ps:/
    /apiblueprint.org
    © Oracle Corpora,on UK Limited, 2018 6

    View full-size slide

  7. 2
    2 h$ps:/
    /swagger.io
    © Oracle Corpora,on UK Limited, 2018 7

    View full-size slide

  8. Apiary Product Surface
    © Oracle Corpora,on UK Limited, 2018 8

    View full-size slide

  9. Apiary Editor
    © Oracle Corpora,on UK Limited, 2018 9

    View full-size slide

  10. Interactive Documentation
    © Oracle Corpora,on UK Limited, 2018 10

    View full-size slide

  11. Interactive Console
    © Oracle Corpora,on UK Limited, 2018 11

    View full-size slide

  12. Traffic Inspector
    © Oracle Corpora,on UK Limited, 2018 12

    View full-size slide

  13. Mock Server
    © Oracle Corpora,on UK Limited, 2018 13

    View full-size slide

  14. Dredd
    © Oracle Corpora,on UK Limited, 2018 14

    View full-size slide

  15. Dredd
    © Oracle Corpora,on UK Limited, 2018 15

    View full-size slide

  16. API Style Guide
    © Oracle Corpora,on UK Limited, 2018 16

    View full-size slide

  17. ... and more
    © Oracle Corpora,on UK Limited, 2018 17

    View full-size slide

  18. Abstract Format
    © Oracle Corpora,on UK Limited, 2018 18

    View full-size slide

  19. Abstract Format
    © Oracle Corpora,on UK Limited, 2018 19

    View full-size slide

  20. Abstract Format
    © Oracle Corpora,on UK Limited, 2018 20

    View full-size slide

  21. Canonical API Description Format
    © Oracle Corpora,on UK Limited, 2018 21

    View full-size slide

  22. API Elements
    © Oracle Corpora,on UK Limited, 2018 22

    View full-size slide

  23. API Elements
    {
    "element": "httpResponse",
    "attributes": {
    "statusCode": {
    "element": "number",
    "content": 200
    }
    },
    "content": [...]
    }
    © Oracle Corpora,on UK Limited, 2018 23

    View full-size slide

  24. API Elements
    {
    "element": "httpResponse",
    "attributes": {
    "statusCode": {
    "element": "number",
    "content": 200
    }
    },
    "content": [...]
    }
    © Oracle Corpora,on UK Limited, 2018 24

    View full-size slide

  25. API Elements
    {
    "element": "string",
    "attributes": {
    "sourceMap": {
    "element": "sourceMap",
    "content": [5, 10]
    }
    },
    "content": "Hello World"
    }
    © Oracle Corpora,on UK Limited, 2018 25

    View full-size slide

  26. API Elements
    © Oracle Corpora,on UK Limited, 2018 26

    View full-size slide

  27. API Elements (JS)
    © Oracle Corpora,on UK Limited, 2018 27

    View full-size slide

  28. Adapters
    © Oracle Corpora,on UK Limited, 2018 28

    View full-size slide

  29. Adapters
    © Oracle Corpora,on UK Limited, 2018 29

    View full-size slide

  30. Process Involved in adding OAS 3
    © Oracle Corpora,on UK Limited, 2018 30

    View full-size slide

  31. © Oracle Corpora,on UK Limited, 2018 31

    View full-size slide

  32. OAS 3: Focus
    • Structure Simplifica/on
    • Improved Re-usability
    © Oracle Corpora,on UK Limited, 2018 32

    View full-size slide

  33. OAS 3: Changes
    • Swagger -> OpenAPI
    • GitHub-flavoured Markdown -> CommonMark
    • YAML
    • 2.0 -> 3.0
    © Oracle Corpora,on UK Limited, 2018 33

    View full-size slide

  34. OAS 3: JSON Schema
    • Larger JSON Schema support
    • oneOf, anyOf, not, and more
    • nullable (x-nullable extension in Swagger 2)
    © Oracle Corpora,on UK Limited, 2018 34

    View full-size slide

  35. OAS 3: Content Negotiation
    © Oracle Corpora,on UK Limited, 2018 35

    View full-size slide

  36. A Visual Guide to What's New in Swagger 3.0 4
    4 h$ps:/
    /blog.readme.io/an-example-filled-guide-to-swagger-3-2/
    © Oracle Corpora,on UK Limited, 2018 36

    View full-size slide

  37. A Visual Guide to What's New in Swagger 3.0 4
    4 h$ps:/
    /blog.readme.io/an-example-filled-guide-to-swagger-3-2/
    © Oracle Corpora,on UK Limited, 2018 37

    View full-size slide

  38. A Visual Guide to What's New in Swagger 3.0 4
    4 h$ps:/
    /blog.readme.io/an-example-filled-guide-to-swagger-3-2/
    © Oracle Corpora,on UK Limited, 2018 38

    View full-size slide

  39. A Visual Guide to What's New in Swagger 3.0 4
    4 h$ps:/
    /blog.readme.io/an-example-filled-guide-to-swagger-3-2/
    © Oracle Corpora,on UK Limited, 2018 39

    View full-size slide

  40. A Visual Guide to What's New in Swagger 3.0 4
    4 h$ps:/
    /blog.readme.io/an-example-filled-guide-to-swagger-3-2/
    © Oracle Corpora,on UK Limited, 2018 40

    View full-size slide

  41. OAS 3: Callbacks
    © Oracle Corpora,on UK Limited, 2018 41

    View full-size slide

  42. OAS 3: Links
    © Oracle Corpora,on UK Limited, 2018 42

    View full-size slide

  43. OAS 3 and API Elements
    © Oracle Corpora,on UK Limited, 2018 43

    View full-size slide

  44. OAS 3 Adoption Plan
    © Oracle Corpora,on UK Limited, 2018 44

    View full-size slide

  45. OAS 3: Phase 1
    Soft Launch
    © Oracle Corpora,on UK Limited, 2018 45

    View full-size slide

  46. OAS 3: Phase 2
    Public Launch
    © Oracle Corpora,on UK Limited, 2018 46

    View full-size slide

  47. OAS 3: Phase 3
    Maturity
    © Oracle Corpora,on UK Limited, 2018 47

    View full-size slide

  48. API Elements
    https://apielements.org
    © Oracle Corpora,on UK Limited, 2018 48

    View full-size slide

  49. © Oracle Corpora,on UK Limited, 2018 49

    View full-size slide

  50. @kylefuller
    [email protected]
    © Oracle Corpora,on UK Limited, 2018 50

    View full-size slide