Más contenido relacionado
La actualidad más candente (20)
Similar a Boost Your Content Strategy for REST APIs (20)
Boost Your Content Strategy for REST APIs
- 1. 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
- 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. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
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
- 4. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Importance of REST APIs
- 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. 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. 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. 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. 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. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Best Practices for REST API content
- 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. 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. 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. 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. 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. 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. 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/
- 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. 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. 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. 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. 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
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. 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. 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
- 25. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Oracle REST APIs
- 26. 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
- 27. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. | 27
Product Build Systems
in DEV Environments
REST Publishing
App
Oracle Authoring Systems
- 28. 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
- 29. 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/
- 30. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
Learn More
- 31. 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
- 32. 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
- 33. 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
- 34. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
What we looked at
Importance of REST APIs
Best practices for REST API content
Oracle REST APIs
Learn more
1
2
3
34
4
- 35. Copyright © 2015, Oracle and/or its affiliates. All rights reserved. |
• @martarauch
• Marta Rauch
• +Marta Rauch
• Marta Rauch
• Marta Rauch
Connect
with me!
Thank You!
- 36. 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 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
- 37. 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.
37