Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

REST API Doc Best Practices

6,106 views

Published on

REST API Documentation Best Practices, by Marta Rauch @martarauch for STC Silicon Valley Chaper meeting, March 16, 2015

Published in: Technology

REST API Doc Best Practices

  1. 1. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | REST API Doc Best Practices Marta Rauch @martarauch STC Silicon Valley Chapter Meeting March, 2015
  2. 2. Copyright © 2015, 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. 2
  3. 3. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | What we’ll look at Importance of REST APIs Best practices for REST API doc Oracle REST APIs – SNEAK PREVIEW Learn more 1 2 3 33/3/2015 4
  4. 4. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Importance of REST APIs
  5. 5. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | • Growing rapidly, industry standard • Fast, scalable, reliable • Great for mobile, wearables, IoT, analytics, SEO REST = REpresentational State Transfer An architecture for client-server web communication 5https://en.wikipedia.org/wiki/Representational_state_transfer Web Technologies, APIs, SOAP, REST - 2014
  6. 6. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Examples: • Cloud services • Mobile apps • Internet of Things (IoT) API = Application Programming Interface Lets products and services communicate with each other 6 http://medianetwork.oracle.com/video/player/3630043914001
  7. 7. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | APIs are growing quickly 7http://www.programmableweb.com/api-research Programmable Web http://www.programmableweb.com/api-research
  8. 8. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Finance and Enterprise are the fastest growing API categories 8 Programmable Web http://www.programmableweb.com/api-research
  9. 9. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | of new APIs are REST APIs 90% 9 http://blog.soa.com/raml-birth-api-description- language-fit-enterprise/
  10. 10. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Best practices for REST API content
  11. 11. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Get developers 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 Content for REST APIs
  12. 12. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Get developers started quickly Why use this API Base URL Get an API key Authentication Error handling HTTP status codes Scenarios, use cases 12 Peter Gruenbaum founder of SDK Bridge Web API Documentation Best Practices The Five Biggest API Doc Mistakes and How To Avoid Them Survey of SDK Documentation Explaining how your API uses OAuth REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  13. 13. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Name Method GET, POST, PUT, DELETE… URL structure Overview Parameters Descriptions Remarks Examples REST endpoints 13 Peter Gruenbaum founder of SDK Bridge Web API Documentation Best Practices Irene Ros, REST API Documentation Best practices for API docs, Andrya Feinberg Include useful reference information REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  14. 14. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Group topics into categories 14 Makes larger API docs more readable REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  15. 15. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Example requests, responses, use cases In the programming languages that your customers use Test code samples 15 API Explorers, by Sarah Maddox Learning how developers think, by Joe Malin A coder’s guide to writing API documentation Code Samples by Tom Johnson Documenting REST APIs, Jody Bleyle Jennifer Rondeau Provide sample code REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  16. 16. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Example: Sample Code 16 Helps developers understand real-world applications REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  17. 17. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Provide quick access to request and response 17 A tabbed UI improves usability REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ http://www.itbusinessedge.com/slideshows/5-ways- to-get-developers-to-adopt-your-apis-02.html
  18. 18. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Example: Request 18 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  19. 19. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Example: Response 19 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  20. 20. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Provide a list of REST endpoints 20 REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ Gives developers an alternate way to access information
  21. 21. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Allows docs to be generated, automated Example frameworks Swagger Raml JSON Schema Hypermedia 21 API Description Languages: Which one is right for me? by Laura Heritage Does one API language fit an entire enterprise? By Laura Heritage Overview of RESTful API Description Languages Represent resources with an API description language https://github.com/swagger-api/swagger- spec/blob/master/examples/v2.0/json/petstore-simple.json
  22. 22. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 22 http://www.itbusinessedge.com/slideshows/5-ways-to-get-developers-to-adopt-your-apis-02.html Automating REST API documentation Peter Gruenbaum founder of SDK Bridge Web API Documentation Best Practices Provide a modern, usable UX REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ Interactive web UI enables quick access to resources and examples
  23. 23. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Get developers 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 Content for REST APIs
  24. 24. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Oracle REST APIs – Sneak Preview
  25. 25. Copyright © 2015, 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 Swagger RAML API docs JSON Schema Hypermedia Publishing app converts to HTML from REST templates Canonical description
  26. 26. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 26 Product Build Systems in DEV Environments REST Publishing App Oracle Authoring Systems
  27. 27. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Swagger and Raml http://swagger.io/ http://swagger.io/specification/ http://raml.org/ http://raml.org/spec.html
  28. 28. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Sample REST API docs 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 Java Cloud Service https://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/
  29. 29. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Learn More
  30. 30. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | Peter Gruenbaum, SDK Bridge: API Documentation 1: JSON and XML for Technical Writers http://sdkbridge.com/online-courses/ API Documentation 2: REST for Writers http://sdkbridge.com/online-courses/ Tom Johnson’s API doc posts http://idratherbewriting.com/category/api-documentation/ and online class http://idratherbewriting.com/docapis_course_overview/ Examples from REST API for Oracle Java Cloud Service: http://docs.oracle.com/cloud/latest/jcs_gs/JSRMR/ 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/ Sarah Maddox, Intro to API technical writing http://www.slideshare.net/sarahmaddox/api-technical-writing Marta Rauch’s API Pinterest posts https://www.pinterest.com/martarauch/apis/ Learn API technical writing https://www.udemy.com/api-documentation-1-json-and-xml/?couponCode=apidoc Learn APIs with Codecademy http://www.codecademy.com/blog/52-learn-apis-with-codecademy Get started, take a class
  31. 31. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | STC webinar API series – Sarah Maddox Intro to APIs, Joe Malin Helping the Code tell the Story Web API Documentation Best Practices by Peter Gruenbaum Documenting your API by Irene Ros Sarah Maddox API posts Documenting REST APIs by Jody Bleyle and Jennifer Rondeau The Five Biggest API Mistakes and how to Avoid Them by Peter Gruenbaum Survey on Documentation by Peter Gruenbaum Good Sample Code by Peter Gruenbaum Creating code samples for API/SDK documentation by Tom Johnson Automating REST API documentation by Tom Johnson and Peter Gruenbaum API Description Languages: Which one is right for me? by Laura Heritage Does one API language fit an entire enterprise? By Laura Heritage REST API documentation Raml: The birth of an API description language fit for enterprise How APIs can enable IDEs Helpful information
  32. 32. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | What we looked at Importance of REST APIs Best practices for REST API doc Oracle REST APIs – SNEAK PREVIEW Learn more 1 2 3 32 4
  33. 33. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | • @martarauch • Marta Rauch • +Marta Rauch • Marta Rauch • Marta Rauch Connect with me! Thank You!
  34. 34. Copyright © 2015, 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 works on REST API guides, developer docs, and integration guides, provides input to corporate REST API standards, and participates with a team that develops a new REST API interface. She also enjoys design jams and developer challenges for mobile, augmented reality, beacons, and wearable technology. A frequent presenter for conferences and webinars, Marta has published articles for IEEE, HCII, STC, and CIDM Best Practices. She contributed information to Developing User Assistance for Mobile Apps, by Joe Welinske, and her augmented reality topic appears in The Language of Content Strategy by Rahel Bailie and Scott Abel. An STC Associate Fellow, Marta has received 15 awards for individual and team projects at the regional and international level. She is VP of the Silicon Valley chapter and a member of the Nominating Committee. She also judges International Summit Awards and reviews Summit proposals Marta has a degree from Stanford University and certificates from Notre Dame and University of California. About the speaker @martarauch
  35. 35. Copyright © 2015, 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. 35
  36. 36. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 36

×