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.

D200a17dd269fd4001bacb11662dab4b?s=128

Kyle Fuller

May 16, 2018
Tweet

Transcript

  1. Preparing for the future of API Description Languages @kylefuller ©

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

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

  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
  5. Apiary Blueprint 2012 - 2014 © Oracle Corpora,on UK Limited,

    2018 5
  6. API Blueprint 1 2014 - Present 1 h$ps:/ /apiblueprint.org ©

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  23. API Elements { "element": "httpResponse", "attributes": { "statusCode": { "element":

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

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

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

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

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

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

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

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

  32. OAS 3: Focus • Structure Simplifica/on • Improved Re-usability ©

    Oracle Corpora,on UK Limited, 2018 32
  33. OAS 3: Changes • Swagger -> OpenAPI • GitHub-flavoured Markdown

    -> CommonMark • YAML • 2.0 -> 3.0 © Oracle Corpora,on UK Limited, 2018 33
  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
  35. OAS 3: Content Negotiation © Oracle Corpora,on UK Limited, 2018

    35
  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
  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
  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
  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
  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
  41. OAS 3: Callbacks © Oracle Corpora,on UK Limited, 2018 41

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

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

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

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

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

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

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

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

  50. @kylefuller kyle.fuller@oracle.com © Oracle Corpora,on UK Limited, 2018 50