SlideShare a Scribd company logo
1 of 52
Download to read offline
© 2015 - Lois Patterson
An example-based approach
(by Lois Patterson)
Creating Good API
Documentation
© 2015 - Lois Patterson
What we will discuss
• Why you want to document APIs
• What APIs are (especially REST APIs)
• How to document APIs, with a focus on
examples
© 2015 - Lois Patterson
Why API Documentation?
As an API documentation writer, you can:
• Wear many hats
• Demonstrate unique, sought-after skill sets
• Work with cutting-edge technology
• Work in a growing space, not a shrinking one
© 2015 - Lois Patterson
Why APIs Matter
• Explosive growth (maybe 200K in 2014?)
• Salesforce, eBay, PayPal, Facebook – Success
by API
• LEGO®-like approach to software
development
• We take interlocking apps for granted now
© 2015 - Lois Patterson
What is an API
• Application Programming Interface
• Snap a software widget into other software
“enablers of remix culture”
“a way for companies and developers to talk
to each other and build off of each other”
(The Atlantic)
© 2015 - Lois Patterson
What is an API
• Example: Many APIs together in one app
© 2015 - Lois Patterson
What is an API
• With an API, “their” software can use and
manipulate “your” software (the parts that
you want to make available)
• Revolutionary and simple
• Focus of this presentation is Internet-enabled
REST APIs
© 2015 - Lois Patterson
Not just skilled developers
You use APIs
Do you ever embed YouTube videos in your
blog?
<iframe width="560" height="315"
src="//www.youtube.com/embed/LJr6Fkn
ZhpM" frameborder="0"
allowfullscreen></iframe>
YouTube provides that code with Share.
© 2015 - Lois Patterson
YouTube Embed Code
© 2015 - Lois Patterson
API to embed video
© 2015 - Lois Patterson
(Flickr, user davenielsen)
“The cloud”? IoT? Think APIs.
© 2015 - Lois Patterson
API Mashups
• Mashup: Glue unrelated bits and pieces
together into a new program
• Google Maps API + a review API + developer
intelligence make a searchable app that tells
us cool restaurants open on Sunday
• Open data great for mashups
• Cloud, InternetOfThings, open data, big data,
social
© 2015 - Lois Patterson
Vast world of APIs
• ProgrammableWeb.com - tens of thousands
of APIs, mashups
• Public APIs for:
Maps
XBox Music Developer
Birdsongs
Facial recognition
Try a search yourself!
• Single application may use multiple APIs
© 2015 - Lois Patterson
APIs: User Analysis
• Typical API user: a software developer
• Mass-market API
Large user base
Less skilled users
• YouTube, Facebook, MailChimp
• Simpler APIs More users
© 2015 - Lois Patterson
Example: Multiple API Usage
Twitter API, AlchemyAPI, Python
language
© 2015 - Lois Patterson
Non-glamorous APIs too
• Device driver APIs
• Internal company APIs
• APIs available to select customers
• Programming language libraries
• Even more of these than public, obvious APIs
© 2015 - Lois Patterson
Why API docs matter
• Without documentation, an API is almost
completely inaccessible.
• For a determined hacker, perhaps possible.
• For typical user without docs, disaster.
• API docs make the API product possible,
much more so than for GUI software.
• Developers do RTFM (read the … manual) for
APIs.
© 2015 - Lois Patterson
Example: Stripe API Docs
© 2015 - Lois Patterson
Good APIs good API docs
• Wear our tech writer hats again
• Start with a good API to make good API docs
• Consistency
• Yes, just like other products
© 2015 - Lois Patterson
Basic techcomm principles
• We know how to get good docs
• Start with a good product
• Start with a good API to make good API docs
• Consistency
• Just like other products
© 2015 - Lois Patterson
REST APIs in a Nutshell
• Verbs (GET, POST, PUT, DELETE, and
sometimes PATCH)
• Nouns (Also called objects or resources)
• Apply verbs to nouns
• Client sends a request (verb + noun) to server
• Server responds to request (a response)
© 2015 - Lois Patterson
REST APIs in a Nutshell
• Verbs + nouns
• Requests + responses
• (And authentication and headers and other
details)
© 2015 - Lois Patterson
REST APIs in a Nutshell
• REST API – a simple and intuitive language
• Guess which company does this with its REST
API?
o Get a movie_ID
o Post (create) a person_ID
o Put (edit by replacing) a rating_ID
o Delete an entry_ID (from a queue)
© 2015 - Lois Patterson
Example: API Consistency and Use
Cases in Netflix
Endpoint for a movie title, by title ID:
http://api-public.netflix.com/catalog/titles/movies/title_id
Endpoint for a TV program, by program ID:
http://api-
public.netflix.com/catalog/titles/programs/program_id
Endpoint for a person, by person ID:
http://api-public.netflix.com/catalog/people/person_id
© 2015 - Lois Patterson
How about PayPal?
© 2015 - Lois Patterson
Some RESTful APIs with great docs
Netflix Twitter
Github Facebook
PayPal New York Times
Google Stripe
SoundCloud Amazon
© 2015 - Lois Patterson
Why are these good API docs?
• Netflix – Well-done API (although Netflix no
longer allows just anyone to use it)
• Soundcloud – Nicely designed, organized
information
• Twitter - Clear definitions of objects and
what you can do with them
• Github – Simple, easy, and everything is
there
© 2015 - Lois Patterson
Good API with good API docs
• Be involved in the beginning.
• Read design documents (they exist, right?)
• Or write the design document
• Write some sample documentation for this
fledgling API – doc first?
• Standard Agile--QA, Tech Pubs,
Development, Product Management work
together in the design phase
© 2015 - Lois Patterson
Important features of a good API
• Consistency
• Good error messages
• Clear naming conventions
• Just like for any other software product!
© 2015 - Lois Patterson
Can your API be as easy as
YouTube?
• Yes! For at least a few features.
• YouTube includes more complicated
features:
https://developers.google.com/youtube/
• A lot of work to get something that simple
• Typical Twitter program (Python) to get a
mass of tweets and save them to a file using
the RESTful API: about 35 lines
© 2015 - Lois Patterson
API success
• Want mass-market adoption?
• Think Simple.
© 2015 - Lois Patterson
What does an API look like?
• Not just code
• You can visualize APIs
© 2015 - Lois Patterson
API Demonstration and Testing
Tools
• Swagger (Django REST Swagger)
• Atlassian REST browser
• Google Advanced REST client
• cURL
Show AND Tell with these tools.
May need developer help—this is for
everyone’s benefit!
© 2015 - Lois Patterson
New York Times Example
© 2015 - Lois Patterson
New York Times Example
© 2015 - Lois Patterson
Pet Store Swagger
© 2015 - Lois Patterson
Pet Store Swagger
© 2015 - Lois Patterson
What goes in the POST box?
JSON: Common format for defining objects and
responses in REST APIs.
{
"name":"Naive Cash Discounting USD",
"format":"f3ml",
"definition":
"<f><n>ExtendModelWithBootstrappedInterpolationCurve</n><a><p><n>AutoSort</n><v><r>
<b>F</b></r></v></p>
<p><n>BaseModel</n><v><r><s>${-
1}</s></r></v></p><p><n>BootstrappingObjective</n><v><r><s>SingleCurrencyValue</s><
/r></v></p>
<p><n>CurveTag</n><v><r><s>USD</s><s>DiscountCurve</s></r></v></p><p><n>Inter
polationMethod</n><v><r><s>LogLinear</s></r></v></p>
<p><n>MarketDataTag</n><v><r><s>CashDeposit:USD</s><s>CashDepo</s></r></v></p
><p><n>ModelName</n><v><r><s></s></r></v></p></a></f>"
}
© 2015 - Lois Patterson
Flickr App Garden
https://www.flickr.com/services/api/explore/?method=flickr.photos.search
A place where developers can showcase the applications they've
created and where you can find new ways to explore Flickr.
© 2015 - Lois Patterson
Your first application
© 2015 - Lois Patterson
PayPal test environment
PayPal
https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
© 2015 - Lois Patterson
API docs should include …
• Description
• Tutorials
• Examples (Snippets, working apps)
• Sandbox test environment
• FAQs
© 2015 - Lois Patterson
Your API docs should have …
• Clear versioning. (And when coding, use
version number of the API.)
• Last-verified date, particularly for Web apps.
• Working code samples
• Suggestions for using API
© 2015 - Lois Patterson
Twitter helps the API user
Twitter site:
There are a few great ways to follow the changes we make to
the Twitter platform:
• Follow @twitterapi.
• Keep track of our Developer Blog and Discussions.
• See the recently updated documentation.
• Consult the Platform Calendar.
© 2015 - Lois Patterson
Twitter API doc page
© 2015 - Lois Patterson
How do I get code samples?
• Laziness and theft encouraged! (Not quite)
• Developers and Test engineers have created
samples for tests (or they should)
• Find and take these samples
• Agree on a standard style for docs
• Build more based on these samples
© 2015 - Lois Patterson
Do I need to code?
• Empathy with our users is a core requirement
for a tech writer
• Learn to read and edit code
• Increase your code-creation abilities
• Coursera, Udacity, Khan Academy, etc.
• Use support groups
• Code samples are the best-loved, but not the
only documentation
© 2015 - Lois Patterson
API Tutorial to try
Sarah Maddox, previously of Atlassian and now
of Google, wrote this tutorial:
http://bit.ly/1SmxwdY
(Or look it up at ffeathers.wordpress.com )
Learn about code, docs, API design in one go!
© 2015 - Lois Patterson
Resources (or the neverending
story)
• Impossible to keep up, but here’s a text file I
have on Google Drive (including links in this
presentation):
http://tinyurl.com/oqfm2mf
© 2015 - Lois Patterson
Enjoy documenting APIs!
• Lots of energy and opportunity in this field
• Always a chance to learn something new
© 2015 - Lois Patterson
© 2015 - Lois Patterson
L.Patterson@fincad.com
@LoisRP

More Related Content

What's hot

Moving into API documentation writing
Moving into API documentation writingMoving into API documentation writing
Moving into API documentation writingEllis Pratt
 
Writing code samples for API/SDK documentation
Writing code samples for API/SDK documentationWriting code samples for API/SDK documentation
Writing code samples for API/SDK documentationTom Johnson
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)Tom Johnson
 
API workshop: Deep dive into Java
API workshop: Deep dive into JavaAPI workshop: Deep dive into Java
API workshop: Deep dive into JavaTom Johnson
 
API Documentation -- Presentation to East Bay STC Chapter
API Documentation -- Presentation to East Bay STC ChapterAPI Documentation -- Presentation to East Bay STC Chapter
API Documentation -- Presentation to East Bay STC ChapterTom Johnson
 
Aye, Aye, API - What makes Technical Communicators uneasy about API document...
Aye, Aye, API  - What makes Technical Communicators uneasy about API document...Aye, Aye, API  - What makes Technical Communicators uneasy about API document...
Aye, Aye, API - What makes Technical Communicators uneasy about API document...Ellis Pratt
 
Rowdy Rabouw - Unleash your web skills on native
Rowdy Rabouw - Unleash your web skills on nativeRowdy Rabouw - Unleash your web skills on native
Rowdy Rabouw - Unleash your web skills on nativeOdessaJS Conf
 
Liferay as a headless platform
Liferay as a headless platform  Liferay as a headless platform
Liferay as a headless platform Jorge Ferrer
 
API Documentation Meetup 2016, London
API Documentation Meetup 2016, LondonAPI Documentation Meetup 2016, London
API Documentation Meetup 2016, LondonChristian Heidenreich
 
Golden Rules of API Design
Golden Rules of API DesignGolden Rules of API Design
Golden Rules of API DesignDavid Koelle
 
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)Ryan Cuprak
 
API Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantAPI Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantVladimir Shulyak
 
Building Cross-Platform Mobile Apps
Building Cross-Platform Mobile AppsBuilding Cross-Platform Mobile Apps
Building Cross-Platform Mobile AppsTroy Miles
 
Why do developers prefer ionic to build progressive web apps
Why do developers prefer ionic to build progressive web apps  Why do developers prefer ionic to build progressive web apps
Why do developers prefer ionic to build progressive web apps Moon Technolabs Pvt. Ltd.
 
Spring Tools 4 - Eclipse and Beyond
Spring Tools 4 - Eclipse and BeyondSpring Tools 4 - Eclipse and Beyond
Spring Tools 4 - Eclipse and BeyondVMware Tanzu
 

What's hot (16)

Moving into API documentation writing
Moving into API documentation writingMoving into API documentation writing
Moving into API documentation writing
 
Writing code samples for API/SDK documentation
Writing code samples for API/SDK documentationWriting code samples for API/SDK documentation
Writing code samples for API/SDK documentation
 
API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)API workshop: Introduction to APIs (TC Camp)
API workshop: Introduction to APIs (TC Camp)
 
API workshop: Deep dive into Java
API workshop: Deep dive into JavaAPI workshop: Deep dive into Java
API workshop: Deep dive into Java
 
API Documentation -- Presentation to East Bay STC Chapter
API Documentation -- Presentation to East Bay STC ChapterAPI Documentation -- Presentation to East Bay STC Chapter
API Documentation -- Presentation to East Bay STC Chapter
 
Aye, Aye, API - What makes Technical Communicators uneasy about API document...
Aye, Aye, API  - What makes Technical Communicators uneasy about API document...Aye, Aye, API  - What makes Technical Communicators uneasy about API document...
Aye, Aye, API - What makes Technical Communicators uneasy about API document...
 
Rowdy Rabouw - Unleash your web skills on native
Rowdy Rabouw - Unleash your web skills on nativeRowdy Rabouw - Unleash your web skills on native
Rowdy Rabouw - Unleash your web skills on native
 
Liferay as a headless platform
Liferay as a headless platform  Liferay as a headless platform
Liferay as a headless platform
 
API Documentation Meetup 2016, London
API Documentation Meetup 2016, LondonAPI Documentation Meetup 2016, London
API Documentation Meetup 2016, London
 
Golden Rules of API Design
Golden Rules of API DesignGolden Rules of API Design
Golden Rules of API Design
 
Mule raml
Mule ramlMule raml
Mule raml
 
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)
Hybrid Mobile Development with Apache Cordova and Java EE 7 (JavaOne 2014)
 
API Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rantAPI Docs Made Right / RAML - Swagger rant
API Docs Made Right / RAML - Swagger rant
 
Building Cross-Platform Mobile Apps
Building Cross-Platform Mobile AppsBuilding Cross-Platform Mobile Apps
Building Cross-Platform Mobile Apps
 
Why do developers prefer ionic to build progressive web apps
Why do developers prefer ionic to build progressive web apps  Why do developers prefer ionic to build progressive web apps
Why do developers prefer ionic to build progressive web apps
 
Spring Tools 4 - Eclipse and Beyond
Spring Tools 4 - Eclipse and BeyondSpring Tools 4 - Eclipse and Beyond
Spring Tools 4 - Eclipse and Beyond
 

Viewers also liked

Introduction To Documentation
Introduction To DocumentationIntroduction To Documentation
Introduction To DocumentationOpenSpace
 
The social and ethical issues of sdd
The social and ethical issues of sddThe social and ethical issues of sdd
The social and ethical issues of sddsarthakgarg97
 
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013Deepak Nadig
 
Journey to APIs and Microservices: Best Practices
Journey to APIs and Microservices: Best PracticesJourney to APIs and Microservices: Best Practices
Journey to APIs and Microservices: Best PracticesDeepak Nadig
 
Good Documentation Practice
Good Documentation PracticeGood Documentation Practice
Good Documentation Practicecr7clark
 

Viewers also liked (6)

Introduction To Documentation
Introduction To DocumentationIntroduction To Documentation
Introduction To Documentation
 
Framemaker 1
Framemaker 1Framemaker 1
Framemaker 1
 
The social and ethical issues of sdd
The social and ethical issues of sddThe social and ethical issues of sdd
The social and ethical issues of sdd
 
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013
Redesigning PayPal APIs for Scale and Simplicity - QCon San Francisco 2013
 
Journey to APIs and Microservices: Best Practices
Journey to APIs and Microservices: Best PracticesJourney to APIs and Microservices: Best Practices
Journey to APIs and Microservices: Best Practices
 
Good Documentation Practice
Good Documentation PracticeGood Documentation Practice
Good Documentation Practice
 

Similar to STC Summit 2015: API Documentation, an Example-Based Approach

The Ultimate API Publisher's Guide
The Ultimate API Publisher's GuideThe Ultimate API Publisher's Guide
The Ultimate API Publisher's GuidePronovix
 
AWS User Group - Survey Results and Building APIs on AWS
AWS User Group - Survey Results and Building APIs on AWSAWS User Group - Survey Results and Building APIs on AWS
AWS User Group - Survey Results and Building APIs on AWSSebastian Krueger
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for LongevityMuleSoft
 
Lessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptxLessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptxapidays
 
Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemMitch Colleran
 
APIs in the Enterprise - Lessons Learned
APIs in the Enterprise - Lessons Learned APIs in the Enterprise - Lessons Learned
APIs in the Enterprise - Lessons Learned Apigee | Google Cloud
 
Top 10 Lessons Learned from the Netflix API - OSCON 2014
Top 10 Lessons Learned from the Netflix API - OSCON 2014Top 10 Lessons Learned from the Netflix API - OSCON 2014
Top 10 Lessons Learned from the Netflix API - OSCON 2014Daniel Jacobson
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product StrategyRavi Kumar
 
API Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraAPI Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraCA API Management
 
INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...
INTERFACE, by apidays  - The 8 Key Components of a Modern API Stack by Iddo G...INTERFACE, by apidays  - The 8 Key Components of a Modern API Stack by Iddo G...
INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...apidays
 
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie MitraAPI Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie MitraCA API Management
 
Documenting APIs (with many pictures of cats) - APIStrat
Documenting APIs (with many pictures of cats) - APIStratDocumenting APIs (with many pictures of cats) - APIStrat
Documenting APIs (with many pictures of cats) - APIStratAnya Stettler
 
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)Introduction to The 6 Insights of API Practice (Bill Doerrfeld)
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)Nordic APIs
 
Service api design validation & collaboration
Service api design validation & collaborationService api design validation & collaboration
Service api design validation & collaborationUchit Vyas ☁
 
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMGapidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMGapidays
 
Building Your API for Longevity
Building Your API for LongevityBuilding Your API for Longevity
Building Your API for LongevityMuleSoft
 
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...CA Technologies
 
Documentation, APIs & AI
Documentation, APIs & AIDocumentation, APIs & AI
Documentation, APIs & AIPronovix
 
Welcome Note by Abhinav Asthana, CEO at Postman
Welcome Note by Abhinav Asthana, CEO at PostmanWelcome Note by Abhinav Asthana, CEO at Postman
Welcome Note by Abhinav Asthana, CEO at PostmanPostman
 

Similar to STC Summit 2015: API Documentation, an Example-Based Approach (20)

The Ultimate API Publisher's Guide
The Ultimate API Publisher's GuideThe Ultimate API Publisher's Guide
The Ultimate API Publisher's Guide
 
AWS User Group - Survey Results and Building APIs on AWS
AWS User Group - Survey Results and Building APIs on AWSAWS User Group - Survey Results and Building APIs on AWS
AWS User Group - Survey Results and Building APIs on AWS
 
Building a REST API for Longevity
Building a REST API for LongevityBuilding a REST API for Longevity
Building a REST API for Longevity
 
Lessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptxLessons learned on the Azure API Stewardship Journey.pptx
Lessons learned on the Azure API Stewardship Journey.pptx
 
Building the Eventbrite API Ecosystem
Building the Eventbrite API EcosystemBuilding the Eventbrite API Ecosystem
Building the Eventbrite API Ecosystem
 
API Conference 2021
API Conference 2021API Conference 2021
API Conference 2021
 
APIs in the Enterprise - Lessons Learned
APIs in the Enterprise - Lessons Learned APIs in the Enterprise - Lessons Learned
APIs in the Enterprise - Lessons Learned
 
Top 10 Lessons Learned from the Netflix API - OSCON 2014
Top 10 Lessons Learned from the Netflix API - OSCON 2014Top 10 Lessons Learned from the Netflix API - OSCON 2014
Top 10 Lessons Learned from the Netflix API - OSCON 2014
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product Strategy
 
API Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraAPI Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie Mitra
 
INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...
INTERFACE, by apidays  - The 8 Key Components of a Modern API Stack by Iddo G...INTERFACE, by apidays  - The 8 Key Components of a Modern API Stack by Iddo G...
INTERFACE, by apidays - The 8 Key Components of a Modern API Stack by Iddo G...
 
API Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie MitraAPI Workshop Amsterdam presented by API Architect Ronnie Mitra
API Workshop Amsterdam presented by API Architect Ronnie Mitra
 
Documenting APIs (with many pictures of cats) - APIStrat
Documenting APIs (with many pictures of cats) - APIStratDocumenting APIs (with many pictures of cats) - APIStrat
Documenting APIs (with many pictures of cats) - APIStrat
 
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)Introduction to The 6 Insights of API Practice (Bill Doerrfeld)
Introduction to The 6 Insights of API Practice (Bill Doerrfeld)
 
Service api design validation & collaboration
Service api design validation & collaborationService api design validation & collaboration
Service api design validation & collaboration
 
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMGapidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG
apidays LIVE New York 2021 - Service API design validation by Uchit Vyas, KPMG
 
Building Your API for Longevity
Building Your API for LongevityBuilding Your API for Longevity
Building Your API for Longevity
 
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...
Pitney Bowes Uses Development and Testing Tools to Drive Early API Developmen...
 
Documentation, APIs & AI
Documentation, APIs & AIDocumentation, APIs & AI
Documentation, APIs & AI
 
Welcome Note by Abhinav Asthana, CEO at Postman
Welcome Note by Abhinav Asthana, CEO at PostmanWelcome Note by Abhinav Asthana, CEO at Postman
Welcome Note by Abhinav Asthana, CEO at Postman
 

Recently uploaded

Cybersecurity and Generative AI - for Good and Bad vol.2
Cybersecurity and Generative AI - for Good and Bad vol.2Cybersecurity and Generative AI - for Good and Bad vol.2
Cybersecurity and Generative AI - for Good and Bad vol.2Ivo Andreev
 
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsYour Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsJaydeep Chhasatia
 
Urbanclap_Clone_Script_On_demand_service.pptx
Urbanclap_Clone_Script_On_demand_service.pptxUrbanclap_Clone_Script_On_demand_service.pptx
Urbanclap_Clone_Script_On_demand_service.pptxNetflix Clone
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesShyamsundar Das
 
Advice for writing a NSERC Discovery grant application v0.5
Advice for writing a NSERC Discovery grant application v0.5Advice for writing a NSERC Discovery grant application v0.5
Advice for writing a NSERC Discovery grant application v0.5Yann-Gaël Guéhéneuc
 
Kubernetes go-live checklist for your microservices.pptx
Kubernetes go-live checklist for your microservices.pptxKubernetes go-live checklist for your microservices.pptx
Kubernetes go-live checklist for your microservices.pptxPrakarsh -
 
Folding Cheat Sheet #2 - second in a series
Folding Cheat Sheet #2 - second in a seriesFolding Cheat Sheet #2 - second in a series
Folding Cheat Sheet #2 - second in a seriesPhilip Schwarz
 
Key projects Data Science and Engineering
Key projects Data Science and EngineeringKey projects Data Science and Engineering
Key projects Data Science and EngineeringVijayananda Mohire
 
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptx
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptxDigital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptx
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptxOffsiteNOC
 
About .NET 8 and a first glimpse into .NET9
About .NET 8 and a first glimpse into .NET9About .NET 8 and a first glimpse into .NET9
About .NET 8 and a first glimpse into .NET9Jürgen Gutsch
 
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...OnePlan Solutions
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesSoftwareMill
 
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...Jaydeep Chhasatia
 
Ptidej Architecture, Design, and Implementation in Action v2.1
Ptidej Architecture, Design, and Implementation in Action v2.1Ptidej Architecture, Design, and Implementation in Action v2.1
Ptidej Architecture, Design, and Implementation in Action v2.1Yann-Gaël Guéhéneuc
 
20240330_고급진 코드를 위한 exception 다루기
20240330_고급진 코드를 위한 exception 다루기20240330_고급진 코드를 위한 exception 다루기
20240330_고급진 코드를 위한 exception 다루기Chiwon Song
 
How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?AmeliaSmith90
 

Recently uploaded (20)

Cybersecurity and Generative AI - for Good and Bad vol.2
Cybersecurity and Generative AI - for Good and Bad vol.2Cybersecurity and Generative AI - for Good and Bad vol.2
Cybersecurity and Generative AI - for Good and Bad vol.2
 
Program with GUTs
Program with GUTsProgram with GUTs
Program with GUTs
 
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsYour Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
 
Urbanclap_Clone_Script_On_demand_service.pptx
Urbanclap_Clone_Script_On_demand_service.pptxUrbanclap_Clone_Script_On_demand_service.pptx
Urbanclap_Clone_Script_On_demand_service.pptx
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security Challenges
 
Advice for writing a NSERC Discovery grant application v0.5
Advice for writing a NSERC Discovery grant application v0.5Advice for writing a NSERC Discovery grant application v0.5
Advice for writing a NSERC Discovery grant application v0.5
 
Kubernetes go-live checklist for your microservices.pptx
Kubernetes go-live checklist for your microservices.pptxKubernetes go-live checklist for your microservices.pptx
Kubernetes go-live checklist for your microservices.pptx
 
Intro to Tendenci AMS - Session 1 - FOSS
Intro to Tendenci AMS - Session 1 - FOSSIntro to Tendenci AMS - Session 1 - FOSS
Intro to Tendenci AMS - Session 1 - FOSS
 
Sustainable Web Design - Claire Thornewill
Sustainable Web Design - Claire ThornewillSustainable Web Design - Claire Thornewill
Sustainable Web Design - Claire Thornewill
 
Folding Cheat Sheet #2 - second in a series
Folding Cheat Sheet #2 - second in a seriesFolding Cheat Sheet #2 - second in a series
Folding Cheat Sheet #2 - second in a series
 
Key projects Data Science and Engineering
Key projects Data Science and EngineeringKey projects Data Science and Engineering
Key projects Data Science and Engineering
 
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptx
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptxDigital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptx
Digital Fortress Secure Remote Server Monitoring for Your Peace of Mind.pptx
 
About .NET 8 and a first glimpse into .NET9
About .NET 8 and a first glimpse into .NET9About .NET 8 and a first glimpse into .NET9
About .NET 8 and a first glimpse into .NET9
 
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...
Revolutionizing IT Project Delivery - Embrace the Future with OnePlan’s AI-Po...
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retries
 
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...
Optimizing Business Potential: A Guide to Outsourcing Engineering Services in...
 
Ptidej Architecture, Design, and Implementation in Action v2.1
Ptidej Architecture, Design, and Implementation in Action v2.1Ptidej Architecture, Design, and Implementation in Action v2.1
Ptidej Architecture, Design, and Implementation in Action v2.1
 
20240330_고급진 코드를 위한 exception 다루기
20240330_고급진 코드를 위한 exception 다루기20240330_고급진 코드를 위한 exception 다루기
20240330_고급진 코드를 위한 exception 다루기
 
How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?How Does the Epitome of Spyware Differ from Other Malicious Software?
How Does the Epitome of Spyware Differ from Other Malicious Software?
 
Intro to Tendenci AMS - Session 2 - FOSS
Intro to Tendenci AMS - Session 2 - FOSSIntro to Tendenci AMS - Session 2 - FOSS
Intro to Tendenci AMS - Session 2 - FOSS
 

STC Summit 2015: API Documentation, an Example-Based Approach

  • 1. © 2015 - Lois Patterson An example-based approach (by Lois Patterson) Creating Good API Documentation
  • 2. © 2015 - Lois Patterson What we will discuss • Why you want to document APIs • What APIs are (especially REST APIs) • How to document APIs, with a focus on examples
  • 3. © 2015 - Lois Patterson Why API Documentation? As an API documentation writer, you can: • Wear many hats • Demonstrate unique, sought-after skill sets • Work with cutting-edge technology • Work in a growing space, not a shrinking one
  • 4. © 2015 - Lois Patterson Why APIs Matter • Explosive growth (maybe 200K in 2014?) • Salesforce, eBay, PayPal, Facebook – Success by API • LEGO®-like approach to software development • We take interlocking apps for granted now
  • 5. © 2015 - Lois Patterson What is an API • Application Programming Interface • Snap a software widget into other software “enablers of remix culture” “a way for companies and developers to talk to each other and build off of each other” (The Atlantic)
  • 6. © 2015 - Lois Patterson What is an API • Example: Many APIs together in one app
  • 7. © 2015 - Lois Patterson What is an API • With an API, “their” software can use and manipulate “your” software (the parts that you want to make available) • Revolutionary and simple • Focus of this presentation is Internet-enabled REST APIs
  • 8. © 2015 - Lois Patterson Not just skilled developers You use APIs Do you ever embed YouTube videos in your blog? <iframe width="560" height="315" src="//www.youtube.com/embed/LJr6Fkn ZhpM" frameborder="0" allowfullscreen></iframe> YouTube provides that code with Share.
  • 9. © 2015 - Lois Patterson YouTube Embed Code
  • 10. © 2015 - Lois Patterson API to embed video
  • 11. © 2015 - Lois Patterson (Flickr, user davenielsen) “The cloud”? IoT? Think APIs.
  • 12. © 2015 - Lois Patterson API Mashups • Mashup: Glue unrelated bits and pieces together into a new program • Google Maps API + a review API + developer intelligence make a searchable app that tells us cool restaurants open on Sunday • Open data great for mashups • Cloud, InternetOfThings, open data, big data, social
  • 13. © 2015 - Lois Patterson Vast world of APIs • ProgrammableWeb.com - tens of thousands of APIs, mashups • Public APIs for: Maps XBox Music Developer Birdsongs Facial recognition Try a search yourself! • Single application may use multiple APIs
  • 14. © 2015 - Lois Patterson APIs: User Analysis • Typical API user: a software developer • Mass-market API Large user base Less skilled users • YouTube, Facebook, MailChimp • Simpler APIs More users
  • 15. © 2015 - Lois Patterson Example: Multiple API Usage Twitter API, AlchemyAPI, Python language
  • 16. © 2015 - Lois Patterson Non-glamorous APIs too • Device driver APIs • Internal company APIs • APIs available to select customers • Programming language libraries • Even more of these than public, obvious APIs
  • 17. © 2015 - Lois Patterson Why API docs matter • Without documentation, an API is almost completely inaccessible. • For a determined hacker, perhaps possible. • For typical user without docs, disaster. • API docs make the API product possible, much more so than for GUI software. • Developers do RTFM (read the … manual) for APIs.
  • 18. © 2015 - Lois Patterson Example: Stripe API Docs
  • 19. © 2015 - Lois Patterson Good APIs good API docs • Wear our tech writer hats again • Start with a good API to make good API docs • Consistency • Yes, just like other products
  • 20. © 2015 - Lois Patterson Basic techcomm principles • We know how to get good docs • Start with a good product • Start with a good API to make good API docs • Consistency • Just like other products
  • 21. © 2015 - Lois Patterson REST APIs in a Nutshell • Verbs (GET, POST, PUT, DELETE, and sometimes PATCH) • Nouns (Also called objects or resources) • Apply verbs to nouns • Client sends a request (verb + noun) to server • Server responds to request (a response)
  • 22. © 2015 - Lois Patterson REST APIs in a Nutshell • Verbs + nouns • Requests + responses • (And authentication and headers and other details)
  • 23. © 2015 - Lois Patterson REST APIs in a Nutshell • REST API – a simple and intuitive language • Guess which company does this with its REST API? o Get a movie_ID o Post (create) a person_ID o Put (edit by replacing) a rating_ID o Delete an entry_ID (from a queue)
  • 24. © 2015 - Lois Patterson Example: API Consistency and Use Cases in Netflix Endpoint for a movie title, by title ID: http://api-public.netflix.com/catalog/titles/movies/title_id Endpoint for a TV program, by program ID: http://api- public.netflix.com/catalog/titles/programs/program_id Endpoint for a person, by person ID: http://api-public.netflix.com/catalog/people/person_id
  • 25. © 2015 - Lois Patterson How about PayPal?
  • 26. © 2015 - Lois Patterson Some RESTful APIs with great docs Netflix Twitter Github Facebook PayPal New York Times Google Stripe SoundCloud Amazon
  • 27. © 2015 - Lois Patterson Why are these good API docs? • Netflix – Well-done API (although Netflix no longer allows just anyone to use it) • Soundcloud – Nicely designed, organized information • Twitter - Clear definitions of objects and what you can do with them • Github – Simple, easy, and everything is there
  • 28. © 2015 - Lois Patterson Good API with good API docs • Be involved in the beginning. • Read design documents (they exist, right?) • Or write the design document • Write some sample documentation for this fledgling API – doc first? • Standard Agile--QA, Tech Pubs, Development, Product Management work together in the design phase
  • 29. © 2015 - Lois Patterson Important features of a good API • Consistency • Good error messages • Clear naming conventions • Just like for any other software product!
  • 30. © 2015 - Lois Patterson Can your API be as easy as YouTube? • Yes! For at least a few features. • YouTube includes more complicated features: https://developers.google.com/youtube/ • A lot of work to get something that simple • Typical Twitter program (Python) to get a mass of tweets and save them to a file using the RESTful API: about 35 lines
  • 31. © 2015 - Lois Patterson API success • Want mass-market adoption? • Think Simple.
  • 32. © 2015 - Lois Patterson What does an API look like? • Not just code • You can visualize APIs
  • 33. © 2015 - Lois Patterson API Demonstration and Testing Tools • Swagger (Django REST Swagger) • Atlassian REST browser • Google Advanced REST client • cURL Show AND Tell with these tools. May need developer help—this is for everyone’s benefit!
  • 34. © 2015 - Lois Patterson New York Times Example
  • 35. © 2015 - Lois Patterson New York Times Example
  • 36. © 2015 - Lois Patterson Pet Store Swagger
  • 37. © 2015 - Lois Patterson Pet Store Swagger
  • 38. © 2015 - Lois Patterson What goes in the POST box? JSON: Common format for defining objects and responses in REST APIs. { "name":"Naive Cash Discounting USD", "format":"f3ml", "definition": "<f><n>ExtendModelWithBootstrappedInterpolationCurve</n><a><p><n>AutoSort</n><v><r> <b>F</b></r></v></p> <p><n>BaseModel</n><v><r><s>${- 1}</s></r></v></p><p><n>BootstrappingObjective</n><v><r><s>SingleCurrencyValue</s>< /r></v></p> <p><n>CurveTag</n><v><r><s>USD</s><s>DiscountCurve</s></r></v></p><p><n>Inter polationMethod</n><v><r><s>LogLinear</s></r></v></p> <p><n>MarketDataTag</n><v><r><s>CashDeposit:USD</s><s>CashDepo</s></r></v></p ><p><n>ModelName</n><v><r><s></s></r></v></p></a></f>" }
  • 39. © 2015 - Lois Patterson Flickr App Garden https://www.flickr.com/services/api/explore/?method=flickr.photos.search A place where developers can showcase the applications they've created and where you can find new ways to explore Flickr.
  • 40. © 2015 - Lois Patterson Your first application
  • 41. © 2015 - Lois Patterson PayPal test environment PayPal https://developer.paypal.com/docs/classic/lifecycle/ug_sandbox/
  • 42. © 2015 - Lois Patterson API docs should include … • Description • Tutorials • Examples (Snippets, working apps) • Sandbox test environment • FAQs
  • 43. © 2015 - Lois Patterson Your API docs should have … • Clear versioning. (And when coding, use version number of the API.) • Last-verified date, particularly for Web apps. • Working code samples • Suggestions for using API
  • 44. © 2015 - Lois Patterson Twitter helps the API user Twitter site: There are a few great ways to follow the changes we make to the Twitter platform: • Follow @twitterapi. • Keep track of our Developer Blog and Discussions. • See the recently updated documentation. • Consult the Platform Calendar.
  • 45. © 2015 - Lois Patterson Twitter API doc page
  • 46. © 2015 - Lois Patterson How do I get code samples? • Laziness and theft encouraged! (Not quite) • Developers and Test engineers have created samples for tests (or they should) • Find and take these samples • Agree on a standard style for docs • Build more based on these samples
  • 47. © 2015 - Lois Patterson Do I need to code? • Empathy with our users is a core requirement for a tech writer • Learn to read and edit code • Increase your code-creation abilities • Coursera, Udacity, Khan Academy, etc. • Use support groups • Code samples are the best-loved, but not the only documentation
  • 48. © 2015 - Lois Patterson API Tutorial to try Sarah Maddox, previously of Atlassian and now of Google, wrote this tutorial: http://bit.ly/1SmxwdY (Or look it up at ffeathers.wordpress.com ) Learn about code, docs, API design in one go!
  • 49. © 2015 - Lois Patterson Resources (or the neverending story) • Impossible to keep up, but here’s a text file I have on Google Drive (including links in this presentation): http://tinyurl.com/oqfm2mf
  • 50. © 2015 - Lois Patterson Enjoy documenting APIs! • Lots of energy and opportunity in this field • Always a chance to learn something new
  • 51. © 2015 - Lois Patterson
  • 52. © 2015 - Lois Patterson L.Patterson@fincad.com @LoisRP