SlideShare uma empresa Scribd logo
1 de 53
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
REST API Doc Best Practices
Marta Rauch
@martarauch
#STC16
STC Summit May 16, 2016
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Listen for your
top takeaways
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Importance of REST APIs
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
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
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
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
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”
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Best practices for REST API content
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
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/
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/
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/
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
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/
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/
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
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
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
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
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/
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
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
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
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
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
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
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
How one company does this
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/
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Useful tools
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Where to go from here
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
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Share a
top takeaway
from the auditorium
and the virtual conference
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
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
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
Copyright © 2016, Oracle and/or its affiliates. All rights reserved. | 52
REST API documentation best practices

Mais conteúdo relacionado

Destaque

API Design Essentials - Akana Platform Overview
API Design Essentials - Akana Platform OverviewAPI Design Essentials - Akana Platform Overview
API Design Essentials - Akana Platform OverviewAkana
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for LongevityMuleSoft
 
What is 'Just Enough' Documentation in Agile?
What is 'Just Enough' Documentation in Agile?What is 'Just Enough' Documentation in Agile?
What is 'Just Enough' Documentation in Agile?Sally Elatta
 
Deep-dive into Microservice Outer Architecture
Deep-dive into Microservice Outer ArchitectureDeep-dive into Microservice Outer Architecture
Deep-dive into Microservice Outer ArchitectureWSO2
 
Understanding Gamification of Business
Understanding Gamification of BusinessUnderstanding Gamification of Business
Understanding Gamification of BusinessBala Iyer
 
Ultimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsUltimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsBill Doerrfeld
 
Beautiful REST+JSON APIs with Ion
Beautiful REST+JSON APIs with IonBeautiful REST+JSON APIs with Ion
Beautiful REST+JSON APIs with IonStormpath
 
Gamification is Here: Build a Winning Plan!
Gamification is Here: Build a Winning Plan!Gamification is Here: Build a Winning Plan!
Gamification is Here: Build a Winning Plan!Marta Rauch
 
Building Beautiful REST APIs with ASP.NET Core
Building Beautiful REST APIs with ASP.NET CoreBuilding Beautiful REST APIs with ASP.NET Core
Building Beautiful REST APIs with ASP.NET CoreStormpath
 
REST API testing with SpecFlow
REST API testing with SpecFlowREST API testing with SpecFlow
REST API testing with SpecFlowAiste Stikliute
 
Gamification Workshop 2010
Gamification Workshop 2010Gamification Workshop 2010
Gamification Workshop 2010Amy Jo Kim
 
Gamification - Defining, Designing and Using it
Gamification - Defining, Designing and Using itGamification - Defining, Designing and Using it
Gamification - Defining, Designing and Using itZac Fitz-Walter
 

Destaque (14)

API Design Essentials - Akana Platform Overview
API Design Essentials - Akana Platform OverviewAPI Design Essentials - Akana Platform Overview
API Design Essentials - Akana Platform Overview
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for Longevity
 
What is 'Just Enough' Documentation in Agile?
What is 'Just Enough' Documentation in Agile?What is 'Just Enough' Documentation in Agile?
What is 'Just Enough' Documentation in Agile?
 
Deep-dive into Microservice Outer Architecture
Deep-dive into Microservice Outer ArchitectureDeep-dive into Microservice Outer Architecture
Deep-dive into Microservice Outer Architecture
 
Understanding Gamification of Business
Understanding Gamification of BusinessUnderstanding Gamification of Business
Understanding Gamification of Business
 
Ultimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation SolutionsUltimate Guide to 30+ API Documentation Solutions
Ultimate Guide to 30+ API Documentation Solutions
 
Beautiful REST+JSON APIs with Ion
Beautiful REST+JSON APIs with IonBeautiful REST+JSON APIs with Ion
Beautiful REST+JSON APIs with Ion
 
Gamification is Here: Build a Winning Plan!
Gamification is Here: Build a Winning Plan!Gamification is Here: Build a Winning Plan!
Gamification is Here: Build a Winning Plan!
 
Building Beautiful REST APIs with ASP.NET Core
Building Beautiful REST APIs with ASP.NET CoreBuilding Beautiful REST APIs with ASP.NET Core
Building Beautiful REST APIs with ASP.NET Core
 
REST API testing with SpecFlow
REST API testing with SpecFlowREST API testing with SpecFlow
REST API testing with SpecFlow
 
RESTful API Design, Second Edition
RESTful API Design, Second EditionRESTful API Design, Second Edition
RESTful API Design, Second Edition
 
Gamification Workshop 2010
Gamification Workshop 2010Gamification Workshop 2010
Gamification Workshop 2010
 
Gamification - Defining, Designing and Using it
Gamification - Defining, Designing and Using itGamification - Defining, Designing and Using it
Gamification - Defining, Designing and Using it
 
Gamification strategies
Gamification strategiesGamification strategies
Gamification strategies
 

Mais de Marta Rauch

Boost Your Content Strategy for REST APIs
Boost Your Content Strategy for REST APIsBoost Your Content Strategy for REST APIs
Boost Your Content Strategy for REST APIsMarta Rauch
 
Delighting mobile customers with content for apps, videos, and a social media...
Delighting mobile customers with content for apps, videos, and a social media...Delighting mobile customers with content for apps, videos, and a social media...
Delighting mobile customers with content for apps, videos, and a social media...Marta Rauch
 
Mobile Trends and Innovations
Mobile Trends and InnovationsMobile Trends and Innovations
Mobile Trends and InnovationsMarta Rauch
 
Rauch delighting mobile customers with content for apps, videos, and a social...
Rauch delighting mobile customers with content for apps, videos, and a social...Rauch delighting mobile customers with content for apps, videos, and a social...
Rauch delighting mobile customers with content for apps, videos, and a social...Marta Rauch
 
Google Glass and Augmented Reality - tools for your content strategy tool kit
Google Glass and Augmented Reality - tools for your content strategy tool kitGoogle Glass and Augmented Reality - tools for your content strategy tool kit
Google Glass and Augmented Reality - tools for your content strategy tool kitMarta Rauch
 
Wearables and Google Glass
Wearables and Google GlassWearables and Google Glass
Wearables and Google GlassMarta Rauch
 
Augmented Reality and Google Glass
Augmented Reality and Google GlassAugmented Reality and Google Glass
Augmented Reality and Google GlassMarta Rauch
 
Google Glass is Here! What's Real, What's Hype, and What's Just Cool
 Google Glass is Here! What's Real, What's Hype, and What's Just Cool Google Glass is Here! What's Real, What's Hype, and What's Just Cool
Google Glass is Here! What's Real, What's Hype, and What's Just CoolMarta Rauch
 
Using a Gamification Framework to Start Your Own Gamification Project
Using a Gamification Framework to Start Your Own Gamification ProjectUsing a Gamification Framework to Start Your Own Gamification Project
Using a Gamification Framework to Start Your Own Gamification ProjectMarta Rauch
 
Augmented Reality and Google Glass
Augmented Reality and Google GlassAugmented Reality and Google Glass
Augmented Reality and Google GlassMarta Rauch
 
Game On: Creating User Assistance for Gamified Products
Game On: Creating User Assistance for Gamified ProductsGame On: Creating User Assistance for Gamified Products
Game On: Creating User Assistance for Gamified ProductsMarta Rauch
 
Mobile Content Prototyping - Jump Start Your Mobile Project
Mobile Content Prototyping - Jump Start Your Mobile ProjectMobile Content Prototyping - Jump Start Your Mobile Project
Mobile Content Prototyping - Jump Start Your Mobile ProjectMarta Rauch
 
Mobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMarta Rauch
 
Enterprise Gamification
Enterprise GamificationEnterprise Gamification
Enterprise GamificationMarta Rauch
 
Mobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMarta Rauch
 
Innovations in User Assistance
Innovations in User AssistanceInnovations in User Assistance
Innovations in User AssistanceMarta Rauch
 
12 Key Mobile Usability Guidelines to Implement Now
12 Key Mobile Usability Guidelines to Implement Now12 Key Mobile Usability Guidelines to Implement Now
12 Key Mobile Usability Guidelines to Implement NowMarta Rauch
 
Rauch Lava Con Mobile Usability 2011
Rauch Lava Con Mobile Usability 2011Rauch Lava Con Mobile Usability 2011
Rauch Lava Con Mobile Usability 2011Marta Rauch
 
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta RauchMarta Rauch
 

Mais de Marta Rauch (19)

Boost Your Content Strategy for REST APIs
Boost Your Content Strategy for REST APIsBoost Your Content Strategy for REST APIs
Boost Your Content Strategy for REST APIs
 
Delighting mobile customers with content for apps, videos, and a social media...
Delighting mobile customers with content for apps, videos, and a social media...Delighting mobile customers with content for apps, videos, and a social media...
Delighting mobile customers with content for apps, videos, and a social media...
 
Mobile Trends and Innovations
Mobile Trends and InnovationsMobile Trends and Innovations
Mobile Trends and Innovations
 
Rauch delighting mobile customers with content for apps, videos, and a social...
Rauch delighting mobile customers with content for apps, videos, and a social...Rauch delighting mobile customers with content for apps, videos, and a social...
Rauch delighting mobile customers with content for apps, videos, and a social...
 
Google Glass and Augmented Reality - tools for your content strategy tool kit
Google Glass and Augmented Reality - tools for your content strategy tool kitGoogle Glass and Augmented Reality - tools for your content strategy tool kit
Google Glass and Augmented Reality - tools for your content strategy tool kit
 
Wearables and Google Glass
Wearables and Google GlassWearables and Google Glass
Wearables and Google Glass
 
Augmented Reality and Google Glass
Augmented Reality and Google GlassAugmented Reality and Google Glass
Augmented Reality and Google Glass
 
Google Glass is Here! What's Real, What's Hype, and What's Just Cool
 Google Glass is Here! What's Real, What's Hype, and What's Just Cool Google Glass is Here! What's Real, What's Hype, and What's Just Cool
Google Glass is Here! What's Real, What's Hype, and What's Just Cool
 
Using a Gamification Framework to Start Your Own Gamification Project
Using a Gamification Framework to Start Your Own Gamification ProjectUsing a Gamification Framework to Start Your Own Gamification Project
Using a Gamification Framework to Start Your Own Gamification Project
 
Augmented Reality and Google Glass
Augmented Reality and Google GlassAugmented Reality and Google Glass
Augmented Reality and Google Glass
 
Game On: Creating User Assistance for Gamified Products
Game On: Creating User Assistance for Gamified ProductsGame On: Creating User Assistance for Gamified Products
Game On: Creating User Assistance for Gamified Products
 
Mobile Content Prototyping - Jump Start Your Mobile Project
Mobile Content Prototyping - Jump Start Your Mobile ProjectMobile Content Prototyping - Jump Start Your Mobile Project
Mobile Content Prototyping - Jump Start Your Mobile Project
 
Mobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement Now
 
Enterprise Gamification
Enterprise GamificationEnterprise Gamification
Enterprise Gamification
 
Mobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement NowMobile Usability Guidelines to Implement Now
Mobile Usability Guidelines to Implement Now
 
Innovations in User Assistance
Innovations in User AssistanceInnovations in User Assistance
Innovations in User Assistance
 
12 Key Mobile Usability Guidelines to Implement Now
12 Key Mobile Usability Guidelines to Implement Now12 Key Mobile Usability Guidelines to Implement Now
12 Key Mobile Usability Guidelines to Implement Now
 
Rauch Lava Con Mobile Usability 2011
Rauch Lava Con Mobile Usability 2011Rauch Lava Con Mobile Usability 2011
Rauch Lava Con Mobile Usability 2011
 
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch
7 Key Mobile Usability Guidelines to Implement Now, LavaCon 2011, Marta Rauch
 

Último

Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Brian Pichman
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemAsko Soukka
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1DianaGray10
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAshyamraj55
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxMatsuo Lab
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6DianaGray10
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URLRuncy Oommen
 
9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding TeamAdam Moalla
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Websitedgelyza
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Adtran
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintMahmoud Rabie
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfAijun Zhang
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesDavid Newbury
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsSafe Software
 
NIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopNIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopBachir Benyammi
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Will Schroeder
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 

Último (20)

Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )Building Your Own AI Instance (TBLC AI )
Building Your Own AI Instance (TBLC AI )
 
Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystem
 
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1UiPath Platform: The Backend Engine Powering Your Automation - Session 1
UiPath Platform: The Backend Engine Powering Your Automation - Session 1
 
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPAAnypoint Code Builder , Google Pub sub connector and MuleSoft RPA
Anypoint Code Builder , Google Pub sub connector and MuleSoft RPA
 
Introduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptxIntroduction to Matsuo Laboratory (ENG).pptx
Introduction to Matsuo Laboratory (ENG).pptx
 
UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6UiPath Studio Web workshop series - Day 6
UiPath Studio Web workshop series - Day 6
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URL
 
9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team9 Steps For Building Winning Founding Team
9 Steps For Building Winning Founding Team
 
COMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a WebsiteCOMPUTER 10 Lesson 8 - Building a Website
COMPUTER 10 Lesson 8 - Building a Website
 
Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™Meet the new FSP 3000 M-Flex800™
Meet the new FSP 3000 M-Flex800™
 
Empowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership BlueprintEmpowering Africa's Next Generation: The AI Leadership Blueprint
Empowering Africa's Next Generation: The AI Leadership Blueprint
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdf
 
Linked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond OntologiesLinked Data in Production: Moving Beyond Ontologies
Linked Data in Production: Moving Beyond Ontologies
 
20230104 - machine vision
20230104 - machine vision20230104 - machine vision
20230104 - machine vision
 
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration WorkflowsIgniting Next Level Productivity with AI-Infused Data Integration Workflows
Igniting Next Level Productivity with AI-Infused Data Integration Workflows
 
NIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 WorkshopNIST Cybersecurity Framework (CSF) 2.0 Workshop
NIST Cybersecurity Framework (CSF) 2.0 Workshop
 
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
Apres-Cyber - The Data Dilemma: Bridging Offensive Operations and Machine Lea...
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 

REST API documentation best practices

  • 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