REST API Doc Best Practices

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

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 doc
Oracle REST APIs – SNEAK PREVIEW
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
http://www.itbusinessedge.com/slideshows/5-ways-
to-get-developers-to-adopt-your-apis-02.html

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
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
Interactive
web UI
enables
quick access
to resources
and examples

Oracle REST APIs – Sneak Preview

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 doc
Oracle REST APIs – SNEAK PREVIEW
Learn more
1
2
3
32
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, 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

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

REST API Doc Best Practices

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Destaque

Destaque (12)

Semelhante a REST API Doc Best Practices

Semelhante a REST API Doc Best Practices (20)

Mais de Marta Rauch

Mais de Marta Rauch (19)

Último

Último (20)

REST API Doc Best Practices