Boost Your Content Strategy for REST APIs

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Boost Your Content Strategy
for REST APIs
Marta Rauch
@martarauch
Information Development World
October 1, 2015

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

What we’ll look at
Importance of REST APIs
Best practices for REST API content
Oracle REST APIs
Learn more
1
2
3
33/3/2015
4

• 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

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

APIs are growing quickly
7http://www.programmableweb.com/api-research
Programmable Web
http://www.programmableweb.com/api-research

Finance and Enterprise are the fastest growing API categories
8
Programmable Web
http://www.programmableweb.com/api-research

of new APIs are REST APIs
90%
9
http://blog.soa.com/raml-birth-api-description-
language-fit-enterprise/

Best Practices for REST API content

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

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/

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/

Group topics
into
categories
14
Makes larger
API docs
more
readable

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

Example:
Sample Code
16
Helps developers
understand
real-world
applications

Provide quick access
to request and
response
17
A tabbed UI
improves
usability

Example:
Request
18

Example:
Response
19

Provide a list of REST endpoints
20
Gives developers
an alternate
way
to access
information

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

Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 22
Peter Gruenbaum founder of SDK Bridge Web
API Documentation Best Practices
Automating REST API documentation
Provide a modern, usable UX
Interactive
web UI
enables
quick access
to resources
and examples

Oracle REST APIs

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

Product Build Systems
in DEV Environments
REST Publishing
App
Oracle Authoring Systems

Swagger and Raml
http://swagger.io/
http://swagger.io/specification/
http://raml.org/
http://raml.org/spec.html

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/

Learn More

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

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

What we looked at
Best practices for REST API content
Oracle REST APIs
Learn more
1
2
3
34
4

• @martarauch
• Marta Rauch
• +Marta Rauch
• Marta Rauch
• Marta Rauch
Connect
with me!
Thank You!

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 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 participating in design jams and developer challenges for mobile, augmented reality, beacons,
Internet of Things, data visualization, 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 her projects at the regional and international level. She is VP
of the Silicon Valley chapter and a member of the Nominating Committee. She is Tools & Development track manager
for Summit 2016 proposals, and judges International Summit Awards.
Marta has a degree from Stanford University and certificates from Notre Dame De Namur and University of California.
About the speaker @martarauch

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

Boost Your Content Strategy for REST APIs

Boost Your Content Strategy for REST APIs

Recommended

More Related Content

What's hot (20)

Viewers also liked (7)

Similar to Boost Your Content Strategy for REST APIs (20)

More from Marta Rauch (19)

Recently uploaded (20)

Boost Your Content Strategy for REST APIs