REST API documentation best practices presented by Marta Rauch at #STC16. Provides tips and strategies for providing an excellent developer UX to satisfy your developer audience. Gives examples of Oracle Cloud REST APIs for Java, Internet of Things, Mobile, Social Data and Insight. Also includes a REST API catalog and resources for learning more,

1. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
REST API Doc Best Practices
Marta Rauch
@martarauch
#STC16
STC Summit May 16, 2016

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

5. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Listen for your
top takeaways

6. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Importance of REST APIs

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

9. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
APIs are growing quickly
9@martarauch #stc16
Programmable Web
http://www.programmableweb.com/api-research

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”

12. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Best practices for REST API content

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

32. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 32http://docs.oracle.com/cloud/latest/apicatalog-cloud/APIRR/@martarauch #stc16
Oracle API Catalog
Cloud Service
REST API

33. 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

34. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
How one company does this

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

38. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
GitHub
https://help.github.com/
categories/bootcamp/
Great resources:
GitHub Help
GitHub Hello World
@martarauch #stc16

39. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Useful tools

40. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
REST Clients
40
https://chrome.google.com/webstore/detail/advanced-rest-
client/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-rest-
client/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

43. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Where to go from here

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

47. 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

48. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Share a
top takeaway
from the auditorium
and the virtual conference

49. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |@martarauch #stc16
Use these REST API
documentation best practices
in your own projects
to increase developer satisfaction

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

52. Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 52