api workshop: introduction to apis (tc camp)
TRANSCRIPT
![Page 1: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/1.jpg)
API Documentation Workshop: Introduction to APIs
By Tom Johnson
www.idratherbewriting.com
January 24, 2015
![Page 2: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/2.jpg)
"Complete and accurate documentation" is most important factor in APIs, according to a survey by @programmableweb. 250 respondents.
Important factors in API doc
![Page 3: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/3.jpg)
Presentation by John Musser, founder of programmableweb.com,which has directory of 12,000+ APIs
![Page 5: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/5.jpg)
Says, “The client wants to find someone who'll emulate
Dropbox's developer documentation”
![Page 6: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/6.jpg)
Docs are how users navigate an API product.
With APIs, docs are the interface
![Page 7: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/7.jpg)
More info
needed
![Page 8: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/8.jpg)
Slides + recording + code samples are freely downloadable
![Page 9: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/9.jpg)
About me
• Started doing API/SDK documentation a couple of years ago.
• Am still learning a ton, but enjoy this type of documentation a lot.
• English major / writing background. Not a programmer, but I do like code.
• Blog and podcast at idratherbewriting.com
Disclaimer: There’s a lot of things I simply do not know.
![Page 10: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/10.jpg)
Helpful to install for activities
• Eclipse for Java developers
• Chrome
• Chrome JSON Formatter extension
• Chrome Advanced REST client
• Sublime Text (Mac) or Notepad++ (Win)
• Git
No need to have prior knowledge of programming…
![Page 11: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/11.jpg)
Download workshop files
1. Go to https://github.com/tomjohnson1492/apiworkshop.
2. Click Download Zip. (Or bonus, clone the repo.)
3. Unzip.
![Page 12: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/12.jpg)
Tentative Outline
1. Introduction to API doc
2. Deep dive into REST API doc
3. Deep dive into code samples
3. Deep dive into Java and Javadoc
![Page 13: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/13.jpg)
INTRODUCTION TO API DOC
![Page 14: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/14.jpg)
Questions welcome at anytime
• What’s the biggest question you have about API documentation?
![Page 15: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/15.jpg)
Some basics about the API landscape
System BSystem A
An API is an interface between two systems.
Lots of different types of APIs – for example:
1. Platform APIs that you download and add to your project before compiling.
2. REST APIs that you access through HTTP web requests.
![Page 16: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/16.jpg)
SDK versus API
• API (application programming interface): An interface that provides endpoints, classes, or other functions.
• SDK (software development kit): A set of implementation tools to make it easier to work with an API.
SDK example: A JavaScript SDK that allows you to work with a particular REST API using JavaScript syntax as your implementation format.
![Page 17: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/17.jpg)
Auto-doc with Platform APIs/**
* Reverses the order of the elements in the specified list.<p>
*
* This method runs in linear time.
*
*
* @param list the list whose elements are to be reversed.
* @throws UnsupportedOperationException if the specified list or
* its list-iterator does not support the <tt>set</tt>
operation.
*/
public static void reverse(List<?> list) {
int size = list.size()
if (size < REVERSE_THRESHOLD || list instanceof
RandomAccess) {
for (int i=0, mid=size>>1, j=size-1; i<mid;
i++, j--)
swap(list, i, j);
} else {
…
Add documentation in the source code, structuring it with specific syntax that a documentation generator can read.
![Page 18: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/18.jpg)
Comments get rendered into Javadoc
- Commonly used.- Works only for Java.- Run it from your IDE.- Automate into builds.- Explore other doclets.- Has frame-based -output.- Can skin with CSS.- Looks professional.
![Page 19: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/19.jpg)
Doxygen
- Commonly used.- Works with Java, C++, C#, and others.- Has easy front-end GUI.- Point it at your source files.- Automate into builds.- Can include non-source files (Markdown).- Frame-based output.- Skinnable.
![Page 20: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/20.jpg)
Good example of source-gen. doc
https://www.dropbox.com/developers/coreEach language uses a doc generator for that language.
https://www.dropbox.com/developers/core
![Page 21: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/21.jpg)
Pros of in-source documentation
- Avoids documentation drift
- Allows the person who creates the code (and so best understands it) to also document it
- Includes tooltips when others incorporate the library into their projects- Integrates into developer’s IDE
Doc
SrcDoc Src
Continental drift
![Page 22: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/22.jpg)
Pros/cons with Platform APIs
ProsPerformance: Performance is faster. (REST APIs struggle with latency for web calls.)
Security: More secure.
ConsLanguage coverage: Harder for devs to create APIs for each language (C++, Java, etc.). As prog. languages proliferate, it’s harder to keep up.
Upgrades: Once clients install, it’s hard to encourage upgrades to latest versions.
![Page 23: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/23.jpg)
API doc includes non-ref doc
Although reference doc tends to receive the most attention, these docs are just one part of API documentation. What technical writers often work on is the implementation guide or programmer’s guide on how to use the API. This guide covers task-based information that shows endpoints or classes used in particular workflows and sequences to accomplish goals.
![Page 25: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/25.jpg)
REST API basics
URLs requests return specific data HTTP Request
Re
spo
nse
![Page 26: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/26.jpg)
Responses in JSON or XML
Configuration parameters
Re
spo
nse
in J
SON
fo
rmat
![Page 27: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/27.jpg)
Add parameters to endpoints
https://api.flickr.com/services/rest/?method=flickr.activity.userPhotos&api_key=1712c56e30dbad5ef736245cda0d1cb9&per_page=10&format=json&nojsoncallback=1
Knowing what parameters you can include with an endpoint is a huge part of the REST API documentation.
![Page 28: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/28.jpg)
cURL calls
HTTP requests are often demonstrated through cURL calls, with different HTTP methods:
GET – retrievePOST – editPUT – createDELETE – remove
You can use a command line to pass cURL calls, and you can specify different HTTP methods.
Many sample REST calls are demonstrated in cURL.
![Page 29: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/29.jpg)
With REST APIs, auto-doc not as common b/c source lang. varies
“The beauty of Web APIs is that they can be written in whatever language you like and in whatever manner you like. As long as when an HTTP request comes in, the proper HTTP response goes out, it doesn't matter how it actually happens on the server. But this very flexibility makes automated documentation nearly impossible, since there's no standard mapping between what an API request is and what the code is that generates its response.”-- Kin Lane, APIevangelist.com
![Page 30: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/30.jpg)
Autodoc possibility: Swagger spec
![Page 31: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/31.jpg)
RAML (REST API modeling language)
![Page 32: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/32.jpg)
Swagger UI can parse the Swagger syntax and render an output
Generates an endpoint based on values you enter
![Page 33: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/33.jpg)
Mashery with Klout
Doc becomes interactive when you’re signed in.
htt
p:/
/dev
elo
per
.klo
ut.
com
/io
-do
cs
![Page 34: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/34.jpg)
Mashery.io
This is an API for USA Today. The Swagger and RAML parsers essentially create an API explorer experience with some doc mixed in.
http://developer.usatoday.com/io-docs
![Page 35: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/35.jpg)
Swagger spec can be in source code or in separate YML file
• Swagger spec syntax can be separate yml file or integrated in code using a specific Swagger library
• Swagger has various libraries for different languages.
• Swagger spec is different from Swagger UI
• RAML is a competing spec to Swagger
![Page 36: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/36.jpg)
Information survey on my blog
• 42 respondents working in API documentation
• Many people polled from API Documentation group on Linkedin + blogosphere
![Page 37: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/37.jpg)
Types of APIs that writers document
0%
10%
20%
30%
40%
50%
60%
70%
80%
90%
![Page 38: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/38.jpg)
Are you automating REST API docs?
No Yes N/A
0%
10%
20%
30%
40%
50%
60%
70%
Percent
![Page 39: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/39.jpg)
How are you automating REST API docs?
• - custom scripts• - custom tooling• - homegrown framework• - homegrown Python scripts• - custom tooling• - Swagger• - Swagger• - Swagger• - Corilla.co• - code responses auto-generated• - some code samples auto-generated
![Page 40: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/40.jpg)
Authoring tools used by API doc writers
0
10
20
30
40
50
60
70
80
![Page 41: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/41.jpg)
Do you test out the API calls used in your doc yourself?
Yes No Sometimes
0%
10%
20%
30%
40%
50%
60%
![Page 42: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/42.jpg)
What IDE do you use?
Eclipse None Visual Studio IntelliJ IDEA Xcode Other
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%
![Page 43: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/43.jpg)
Most common programming languages tech writers know
0
5
10
15
20
25
![Page 44: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/44.jpg)
Do developers write the initial API documentation in the source code?
Yes No Sometimes
28%
29%
30%
31%
32%
33%
34%
35%
36%
37%
![Page 45: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/45.jpg)
Do you write doc by looking in the source code?
Yes No
0%
10%
20%
30%
40%
50%
60%
70%
![Page 46: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/46.jpg)
How do you access the source code?
Git Perforce No access tocode
SVN Other Mercurial
0%
5%
10%
15%
20%
25%
30%
35%
40%
![Page 47: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/47.jpg)
Most difficult part of API doc?
Understandcode
Get info fromengineers
Create non-refdocs
Understandaudience
Identifydependencies
0%
5%
10%
15%
20%
25%
30%
35%
40%
45%
50%
Percent
![Page 48: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/48.jpg)
How did you learn what you needed to know?
0%5%
10%15%20%25%30%35%40%45%50%
![Page 49: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/49.jpg)
Takeaways from survey
• Java, Eclipse, Git are popular
• Become familiar with getting info from both source code and developers
• Become a self-learner but also interact heavily with engineers
• REST APIs are by far most common
• Automating REST API doc isn’t all that common
![Page 51: API workshop: Introduction to APIs (TC Camp)](https://reader034.vdocuments.us/reader034/viewer/2022042615/55a699b51a28ab90668b45b9/html5/thumbnails/51.jpg)
Image credits
• slide 2: "API consumers want reliability, documentation and community." Programmableweb.com. http://bit.ly/progwebsurvey
• slide 3: “10 Reasons Developers Hate Your API” (and what to do about it). By John Musser. Slideshare. http://slidesha.re/1pnnDRf
• slide 4: Mars, once. By Kevin Dooley. http://bit.ly/ZFYI0T
• slide 15: Spinning gears. By Brent 2.0. Flickr. http://bit.ly/1DexWM0
• slide 21: Continental Drift. Wikipedia. http://en.wikipedia.org/wiki/Continental_drift
• slide 24: Programmableweb Research Center. http://www.programmableweb.com/api-research