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.

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