API Documentation Languages and Contract First Design

1. API Languages & Contract-First Design John Zaccone - Software Engineer http://www.ipponusa.com

2. Overview ● API Documentation Languages ● Demo ● Contract-First Design ● Refactor the Demo ● Cool Tools 2

3. Let’s REST together 3

4. We need Documentation for our REST APIs ● API Doc Languages define a specification ● Specifications are Machine-Readable ● Parsers and tools that understand the specification can provide great features for little work 4

5. Value Added ● API Doc specifications are open-source ● Value comes from suite of tools and parsers build on that specification ● Interactive documentation, code generation, postman collections, mock servers, traffic inspection, API testing and analytics and much, much more 5

6. Bottom Up or Top Down ● Top-down (aka contract-first) ○ Write doc first ○ Generate code from docs ● Bottom-up ○ Write code first ○ Generate docs from code 6

7. Comparing What’s Out There Swagger RAML API Blueprint Sponsored By Reverb Mulesoft Apiary Initial Commit July, 2011 Sep, 2013 April, 2013 Designed For Code First Contract First Contract First Workgroup Yes Yes No Format JSON w/ YAML YAML Markdown Community 2,386 942 1,614 7

8. Modeling REST They all support: ● Resources ● HTTP Methods ● Query Parameters ● URL Parameters ● Header Parameters ● Status Codes, Content-Types 8

9. Modeling REST Swagger RAML API Blueprint Authentication Basic, API-Key, OAuth2 Basic, Digest, OAuth1, OAuth2 Basic, API-Key, OAuth2 File Inclusions Yes, $ref Yes Nested Resources Yes Yes API Versioning Yes Yes Sample Representations Yes Yes 9

10. Integrations ⭑ Swagger RAML APIBlueprint Server-Side java, scala, ruby, nodejs java Client-Side scala, flash, java, objc, php, python, ruby js Parsers js, java js, java c++, .net, ruby 10

12. Pet Store API ● Get all Pets ● Add a Pet ● Get Pet by ID ● Paging and Security 12

13. A History ● Swagger starts in July 2011, provides API documentation automatically from code ● Push for “contract-first” design ● RAML (Sept, 2013) found that Swagger “was best suited for documenting an existing API, not for designing an API from scratch” ● Swagger 2.0 addresses contract-first design weaknesses (~Sept, 2014) 13

15. Contracts Are Valuable ● Enable 3rd-party developers to build awesome apps ● Channel of revenue ● Drive innovation by sharing internal APIs ● APIs are enablers 15

16. 16

17. Problems ● Doesn’t consider needs of consumers ● Not-so-nice APIs ○ Complicated models ○ Unfriendly business logic ● Consumers might have a different view of the world 17

18. 18

19. API Facade Pattern ● Hide the complexity ● Define an API that users want to use ● Simple models ● Consistent interfaces 19

20. Agile in API Design 20

21. Contract-First Swagger RAML API Blueprint Language Writability Good Good Good Re-usable Patterns Good Great OK Mock Server 3rd Party Yes Yes, External Tool Collaboration Platform Open-Source Solution? Enterprise Offering Enterprise Offering 21

22. Common Patterns in REST ● Many patterns of REST are repeated over and over... ● Get /my_collection ● Post /my_collection ● Filtering, ordering and paging 22

23. Patterns with RAML ● ResourceTypes define common behaviors for resources ● Traits define common behaviors for methods ● Example: /pets type: collection 23

25. Take Away ● Swagger wins ○ Community support ○ Extensive client-side and server-side integrations ● RAML wins ○ Advanced re-use patterns for resources and methods ○ Supports multiple files, and enterprise solution for collaboration ○ Great for designing APIs from scratch 25

26. Keep an Eye Out... ● Community growth in RAML ● Better ways to write APIs in Swagger ● @swagger, @mulesoft ● swagger2raml, raml2swagger 26

28. Client SDK Generator ● https://github.com/swagger- api/swagger-codegen ● Supports a growing list of languages 28

29. RAML API Designer with MongoDB ● https://github.com/brianmc/raml-store 29

30. Enterprise Solutions ● RAML (https://anypoint.mulesoft.com) ● API Blueprint (http://apiary.io/) 30

31. Verify Code == Docs ● Aboa: (https://github.com/cybertk/abao) ● Dredd: (https://github.com/apiaryio/dredd) ● Command-line tool to check if service implementation matches RAML doc ● Integrate into your CI (Jenkins) Build 31

32. API Mashups ● API Notebook (https://api-notebook.anypoint. mulesoft.com) ● Live javascript ● Quickly create clients from RAML definitions ● Make PoC and prototypes ● Saved as Github Gists 32

33. Other ● RAML and Swagger imports into your Postman client ● Sublime plugin for API Blueprint and RAML ● raml2html (https://github. com/kevinrenskers/raml2html) 33

34. Questions ?jzaccone@ipponusa.com @JohnZaccone 34

35. References ● https://speakerdeck.com/apistrat/another-api-blueprint-raml-and-swagger-comparison ● https://blog.soa.com/spread-the-wealth-developer-communities-for-your-apis-part-2-top- down-or-bottom-up-structuring-your-community/ ● https://www.youtube.com/watch?v=vu8_QLkW1mg ● http://apiux.com/2013/04/09/rest-metadata-formats/ ● http://stackoverflow.com/questions/26917188/how-to-break-swagger-2-0-json-file-into- multiple-modules/26917653#26917653 ● http://raml.org/spec.html ● http://stackoverflow.com/users/1103327/ron?tab=answers&sort=votes (Swagger Questions) ● http://www.programmableweb.com/news/reverb-apigee-announce-swagger-2.0- workgroup/2014/05/23 ● http://forums.raml.org/t/how-is-this-different-from-swagger/24 ● https://github.com/swagger-api/swagger-spec/wiki/Swagger-1.2-to-2.0-Migration-Guide 35