REST API documentation best practices

2. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Marta Rauch works in a development team at Oracle, where she architects and leads mobile, cloud, and REST API projects. She develops REST API content, provides input to corporate REST API standards, and participates with a team that developed a new REST API interface. Marta enjoys participating in design jams and developer challenges at her company to prototype solutions for big data, information design, Internet of Things, augmented reality, mobile, and wearable technology. A frequent presenter for conferences and webinars, Marta publishes articles for STC, IEEE, HCII, and CIDM Best Practices. She contributed information to Developing User Assistance for Mobile Apps, by Joe Welinske. Her wearables topic will appear in The Language of Technical Communication, by Ray Gallon and Richard Hamilton, and her augmented reality topic appears in The Language of Content Strategy by Scott Abel and Rahel Bailie. An STC Fellow, Marta has received 15 awards for her projects at the regional and international level. She is VP of the Silicon Valley chapter and a member of the Nominating Committee. She judges International Summit Awards and is #STC16 Tools & Development track manager. Marta has a degree from Stanford University and certificates from Notre Dame De Namur and University of California. @martarauch #STC16 @martarauch #stc16

3. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Safe Harbor Statement The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle. 3@martarauch #stc16

4. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Our agenda Intro and importance of REST APIs Best practices for REST API content How one company does this Useful tools Wrap-up, where to go from here 1 2 3 4 4 5 @martarauch #stc16

7. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Examples Cloud services Mobile, wearable apps Social networks Internet of Things (IoT) API = Application Programming Interface Lets products and services communicate with each other 7@martarauch #stc16 https://cloud.oracle.com/mobile https://youtu.be/J1xstMx3Z_w

8. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Growing rapidly, industry standard Fast, scalable, reliable Useful for cloud, mobile, wearables, IoT, social networks, and more REST = REpresentational State Transfer An architecture for client-server web communication 8https://en.wikipedia.org/wiki/Representational_state_transfer@martarauch #stc16 Example https://youtu.be/N1MVGPdz7_o https://cloud.oracle.com/social-network-cloud

10. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Finance and Enterprise are fast growing API categories 10 Programmable Web http://www.programmableweb.com/api-research @martarauch #stc16

11. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | API docs are critical 11https://en.wikipedia.org/wiki/Representational_state_transfer@martarauch #stc16 Excerpt from Adam DuVander’s API developer survey published on Programmable Web The most important factor for an API is Complete and accurate documentation “Developers want clearly documented APIs”

13. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Help developers get started quickly Include useful reference information Provide sample code Provide a list of REST endpoints Represent resources with a description language Provide a modern, usable UX Best practices for REST API Content @martarauch #stc16

14. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Why use this API Will this help me achieve my goals? 14@martarauch #stc16 Help developers get started quickly REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

15. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Get Started Quick Start 15@martarauch #stc16 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

16. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | URL structure Supported methods 16@martarauch #stc16 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

17. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | GET Retrieve POST Create PUT Update DELETE Delete Example of typical HTTP methods used in REST @martarauch #stc16 https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol

18. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Authentication Get details from your team 18@martarauch #stc16 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

19. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | HTTP status codes and error handling 19@martarauch #stc16 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

20. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Use cases Key tasks for this API 20REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

21. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Task based 21 Include useful reference information REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

22. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Group topics into categories 22 Makes content more readable REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

23. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Name Method URL structure Overview Parameters Descriptions Notes 23REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

24. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Provide quick access to request and response 24 A tabbed UI improves usability REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/

25. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Example Response 25REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

26. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | In languages used by your customers Example requests, responses Test! Helps developers understand real-world use cases 26 Provide sample code REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

27. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Provide a list of REST endpoints 27 Gives developers another way to access information REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

28. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Allows docs to be generated, automated Example: OpenAPI Specification (formerly Swagger) 28 Represent resources with an API description language REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

29. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 29 Provide a modern, usable UX Interactive web UI provides quick access to resources and examples REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ @martarauch #stc16

30. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 30https://cloud.oracle.com/api-catalog@martarauch #stc16 Oracle API Catalog Cloud Service Provide a catalog to expose your APIs

31. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 31https://apicatalog.oraclecloud.com/ui/@martarauch #stc16 Oracle API Catalog Cloud Service UI Machine readable (Swagger 2.0) Lets devs create code stubs Facilitates integration

35. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Demo 35https://cloud.oracle.com/api-catalog@martarauch #stc16 REST APIs for Oracle Java Cloud Service https://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ REST APIs for Oracle Mobile Cloud Service https://docs.oracle.com/cloud/latest/mobilecs_gs/MCSRA/ REST APIs for Oracle Social Data and Insight Cloud Service http://docs.oracle.com/cloud/latest/datacs_common/RRDAT/ REST APIs for Oracle Internet of Things Cloud Service https://docs.oracle.com/cloud/latest/iot/IOTRP/ Oracle Cloud API Catalog https://cloud.oracle.com/api-catalog https://apicatalog.oraclecloud.com/ui/ http://docs.oracle.com/cloud/latest/apicatalog-cloud/APIRR/

36. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | API Documentation Generation To auto-generate API resource reference for docs, development teams • Include required information in the API description for each resource • Adopt one of the API description frameworks recommended to Oracle teams • Use a REST Publishing app to register and publish APIs Open API Initiative (Swagger) API docsJSON Schema Hypermedia Publishing app converts to HTML from REST templates Canonical description @martarauch #stc16

37. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 37 Product Build Systems in DEV Environments REST Publishing App Oracle Authoring Systems (XML, DITA, GitHub) @martarauch #stc16

40. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | REST Clients 40 https://chrome.google.com/webstore/detail/advanced-restclient/hgmloofddffdnphfgcellkdfbfbjeloo?hl=en-US@martarauch #stc16 Postman Advanced REST Client

41. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Example 41 https://chrome.google.com/webstore/detail/advanced-restclient/hgmloofddffdnphfgcellkdfbfbjeloo?hl=en-US@martarauch #stc16 https://thecattlecrew.net/2015/12/15/introducing-the- oracle-iot-cloud-part-iv-the-rest-api/ Using a REST client to register a device on the Internet of Things (IoT) by Pascal Brokmeier

42. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Sample REST clients 42 Interface REST Client Examples Browser Advanced REST Client (Chrome) https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo?hl=en-US Postman (Chrome) https://www.getpostman.com/ REST Easy (Firefox) https://addons.mozilla.org/en-us/firefox/addon/rest-easy/ REST Client (Apple app store) https://itunes.apple.com/us/app/rest-client/id595053691?mt=12 Paw (iOS) https://luckymarmot.com/paw Desktop RESTClient (wiztools.org) http://code.fosshub.com/WizToolsorg-RESTClient/downloads Command line cURL http://curl.haxx.se/download.html @martarauch #stc16

44. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Take Tom Johnson’s online API class http://idratherbewriting.com/docapis_course_overview/ Take Peter Gruenbaum’s online courses from SDK Bridge on Udemy: http://sdkbridge.com/online-courses/ API Documentation 1: JSON and XML for Technical Writers API Documentation 2: REST for Writers API Documentation 3: The Art of API Documentation Check out Ed Marshall’s API & SDK workshop: http://www.marshalldocumentationservices.com/API_SDK_workshop.html Watch the STC webinar API series: Sarah Maddox, Intro to APIs Joe Malin, Helping the Code tell the Story Tom Johnson, Best Practices for Documenting APIs Read the STC Intercom API issue http://intercom.stc.org/magazine/september-2014/features-september-2014/ How do you break into API documentation? http://intercom.stc.org/2014/09/how-do-you-break-into-api-documentation/ Lessons learned as a novice API writer http://intercom.stc.org/2014/09/lessons-learned-as-a-novice-api-writer/ How to write helpful code samples http://intercom.stc.org/2014/09/how-to-write-helpful-code-samples/ Get started, take a class @martarauch #stc16

45. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Tom Johnson’s API doc posts http://idratherbewriting.com/category/api-documentation/ Tom Johnson podcast with Peter Gruenbaum on automating REST API documentation Sarah Maddox, API technical writing http://www.slideshare.net/sarahmaddox/api-technical-writing Programmable Web API Research http://www.programmableweb.com/api-research Kin Lane, API Documentation API Evangelist http://documentation.apievangelist.com/ Marta Rauch’s API Pinterest posts https://www.pinterest.com/martarauch/apis/ Laura Heritage API Description Languages: Which Is the Right One for Me? Jody Bleyle and Jennifer Rondeau Documenting REST APIs Adam DuVander API Consumers Want Reliability, Documentation, and Community Yogeshwar Srikishnan REST API Documentation Part I , REST API Documentation Part II Lorna Mitchell Documentation First: A Recipe for API Success Helpful information @martarauch #stc16

46. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | What we looked at today Intro and importance of REST APIs Best practices for REST API content How one company does this Useful tools Wrap-up, where to go from here 1 2 3 46 4 5 @martarauch #stc16

50. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | • @martarauch • Marta Rauch • +Marta Rauch • Marta Rauch • Marta Rauch Connect with me! Thank you to everyone in the auditorium and in the virtual conference! @martarauch #stc16

51. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | Safe Harbor Statement The preceding is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle. 51