API workshop: Introduction to APIs (TC Camp)

API Documentation Workshop: Introduction to APIs By Tom Johnson www.idratherbewriting.com January 24, 2015

"Complete and accurate documentation" is most important factor in APIs, according to a survey by @programmableweb. 250 respondents. Important factors in API doc

Presentation by John Musser, founder of programmableweb.com, which has directory of 12,000+ APIs

Says, “The client wants to find someone who'll emulate Dropbox's developer documentation”

Docs are how users navigate an API product. With APIs, docs are the interface

Slides + recording + code samples are freely downloadable

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.

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…

Download workshop files 1. Go to https://github.com/tomjohnson1492/apiwor kshop. 2. Click Download Zip. (Or bonus, clone the repo.) 3. Unzip.

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

Questions welcome at anytime • What’s the biggest question you have about API documentation?

Some basics about the API landscape System B System 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.

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.

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.

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.

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.

Good example of source-gen. doc https://www.dropbox.com/developers/core Each language uses a doc generator for that language. https://www.dropbox.com/developers/core

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

Pros/cons with Platform APIs Pros Performance: Performance is faster. (REST APIs struggle with latency for web calls.) Security: More secure. Cons Language 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.

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.

REST API basics URLs requests return specific data HTTP Request Response

Responses in JSON or XML Configuration parameters ResponseinJSONformat

Add parameters to endpoints https://api.flickr.com/services/rest/?method=flic kr.activity.userPhotos&api_key=1712c56e30dbad 5ef736245cda0d1cb9&per_page=10&format=js on&nojsoncallback=1 Knowing what parameters you can include with an endpoint is a huge part of the REST API documentation.

cURL calls HTTP requests are often demonstrated through cURL calls, with different HTTP methods: GET – retrieve POST – edit PUT – create DELETE – 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.

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

Autodoc possibility: Swagger spec

RAML (REST API modeling language)

Swagger UI can parse the Swagger syntax and render an output Generates an endpoint based on values you enter

Mashery with Klout Doc becomes interactive when you’re signed in. http://developer.klout.com/io-docs

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

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

Information survey on my blog • 42 respondents working in API documentation • Many people polled from API Documentation group on Linkedin + blogosphere

Types of APIs that writers document 0% 10% 20% 30% 40% 50% 60% 70% 80% 90%

Are you automating REST API docs? No Yes N/A 0% 10% 20% 30% 40% 50% 60% 70% Percent

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

Authoring tools used by API doc writers 0 10 20 30 40 50 60 70 80

Do you test out the API calls used in your doc yourself? Yes No Sometimes 0% 10% 20% 30% 40% 50% 60%

What IDE do you use? Eclipse None Visual Studio IntelliJ IDEA Xcode Other 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50%

Most common programming languages tech writers know 0 5 10 15 20 25

Do developers write the initial API documentation in the source code? Yes No Sometimes 28% 29% 30% 31% 32% 33% 34% 35% 36% 37%

Do you write doc by looking in the source code? Yes No 0% 10% 20% 30% 40% 50% 60% 70%

How do you access the source code? Git Perforce No access to code SVN Other Mercurial 0% 5% 10% 15% 20% 25% 30% 35% 40%

Most difficult part of API doc? Understand code Get info from engineers Create non-ref docs Understand audience Identify dependencies 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50% Percent

How did you learn what you needed to know? 0% 5% 10% 15% 20% 25% 30% 35% 40% 45% 50%

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

Tom Johnson http://idratherbewriting.com @tomjohnson

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

API workshop: Introduction to APIs (TC Camp)

More Related Content

What's hot

Viewers also liked

Similar to API workshop: Introduction to APIs (TC Camp)

Recently uploaded

API workshop: Introduction to APIs (TC Camp)

Editor's Notes