Blog Archives

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer.
  • Our audience – the developers who need our documentation to use APIs in their applications.
  • The types of API we might be asked to document.
  • Demos of 2 APIs that you can play with yourself.
  • What API documentation consists of.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.

Hope to “see” you at the webinar. 🙂

What is an API client library?

Client libraries are sometimes called helper libraries. What are they and how do they help developers use an API?

Over the past year I’ve run a few workshops on API Technical Writing. Part of the workshop content is about client libraries, and I decided it’s worth discussing this topic in a blog post too. It’s of interest to technical writers who are documenting APIs, particularly web services and REST APIs.

What is a client library?

A client library, sometimes called a helper library, is a set of code that application developers can add to their development projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. For example, a client library may:

  • Provide boiler-plate code needed to create an HTTP request and to process the HTTP response from the API.
  • Include classes that correspond with the elements or data types that the API expects. For example, a Java client library can return native Java objects in the response from the API.
  • Handle user authentication and authorisation.

How is that useful?

Looking at the developer who’s using the API: With a REST API or any web service API, the developer could be using any of a number of programming languages to make the API calls.

Wouldn’t it be great if we could give them some code in their own language, to help them get started with the API? That’s what a client library does. It helps to reduce the amount of code the application developers have to write, and ensures they’re using the API in the best supported manner.

Examples of client libraries

In some cases, the API developers provide client libraries for the API. In other cases, client libraries are developed and supported by the community rather than the API developer.

For example, here are the Flickr API client libraries listed by programming language, all maintained by the developer community:

Here are more examples of client libraries, listed per API:

Is a client library the same thing as an API?

No, although they’re closely related. My post on API types describes library-based APIs, which are libraries of code that developers need to import before they can use the API. So, how does that differ from a client library?

Here’s how I see the difference between library-based APIs and client libraries:

  • Library-based APIs are those where the developer needs to import or reference a library of code or binary functions before the application can interact with the API. For example, the documentation for the Google Maps JavaScript API describes the HTML <script> element needed to load the API library.
  • Client libraries are additional libraries of code that are provided to make a developer’s life easier and to ensure applications follow best practices when using the API. In general, you can call the API directly without using the client library. (In some cases, though, the client libraries may be the preferred or even the only supported means of interacting with a particular service.)

I’d love to hear your thoughts on this topic – does the above summary make sense, is it useful, and what have I left out?

Fledgling Android app for Tech Comm on a Map

I’m very excited, because there’s an Android app on its way for Tech Comm on a Map. The Android app uses the same data source as the Tech Comm on a Map website – so you can see the same events on the map in both apps. In addition, you can add events to the map directly from within the Android app, and it does smart marker clustering too.

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s already out there on the Web. See it in action on the Tech Comm on a Map website, and read more on this page.

And now the Android app

Tech Comm on a Map for Android

The code for the Android app is already on GitHub.  A group of us got together during a hackathon and created the initial version of the app. I’ve added to the app since then, and intend to continue improving it. Eventually I’d like to add it to the Google Play store. There’s a bit to do before that. 🙂

Friendly disclaimer: Although I work at Google, this app is not a Google product. It’s a personal project by me and the other contributors.

The Tech Comm on a Map app for Android is developed with Java and the Android SDK. It uses the following APIs:

If you’re interested in developments, follow the Tech Comm on a Map app for Android on GitHub. You can build it from the source and load it onto your Android device to try it out. It works. 🙂

Introduction to API tech writing – upcoming webinar

On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.

The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!

APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.

Details of the webinar

Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

The session covers the following topics:

  • What an API is and does.
  • Introduction to the role of API technical writer and our audience.
  • Overview of the types of developer products we may be asked to document – APIs and others.
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
  • A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
  • Examples of good API documentation.
  • The components of API documentation, and the technical writer’s role in the creation of each component.
  • A day in the life of an API technical writer.
  • Tips on getting started in the role.

Here’s a link to the slides on SlideShare: API Technical Writing.

Introduction to API technical writing

More in the STC’s webinar series on API technical writing

Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

I hope to “see” you at the webinar!

API explorers – play with a REST API the easy way

To communicate with a REST API (or other web service API), you need to construct a request, send it over HTTP or HTTPS, then receive and parse the response. When creating an app, you do all that with code. But what if you just want to take a look around the API to see what it offers, before diving into the code? API explorers are your friend.

I’ve been putting together some information for a workshop on API technical writing. It’s been a rewarding exercise, because it’s made me think in a structured, educational way about what I do every day. A section of the workshop deals with various online API explorers that I’ve discovered over an extended period of time. This information is likely to be useful to many people, so I’m sharing it in a blog post.

API explorers offer a handy GUI alternative to a command-line tool like cURL. This blog post introduces the Advanced REST Client, which is a generic GUI for interacting with any REST API, and a few API explorers that interact with specific APIs.

Advanced REST Client

The Advanced REST Client is an add-on for Chrome browser. I find it very useful for sending a request to a REST API and receiving the response.

The Advanced REST Client offers a generic web form that you can use to craft an HTTP request, submit the request, and see the response. The screenshot below shows the Advanced REST Client in a Chrome tab. The top text box contains a request for the Flickr REST API. You can see the URL path and the URL parameters specifying the options needed for this particular request: the method (get public photos), the user ID of the person whose photos you want, and an API key.

(Click the image to see a larger version.)

There are more, similar add-ons for Chrome, such as the REST Console and Postman. I haven’t looked at extensions for other browsers, but I’m guessing there are similar tools for them too.

Explorers for specific APIs

Developers of REST APIs and other web service APIs sometimes offer an API explorer, which people can use to take a look around the API before diving into the code.

The principle is the same as the Advanced REST client: an API explorer provides an online form where you can enter the parameters required for an API request, submit the request, and see the results.

The difference is that an API explorer is written for a specific API, whereas the Advanced REST Client is generic. The explorer therefore knows more about the API that it’s accessing. It can therefore:

  • Present specific input boxes for the expected URL parameters and the input data expected in the request body.
  • Hide such pesky complexities as user authentication. In many cases, you can sign in as a user of the web service, and the API explorer will create any authentication tokens that you need.

Flickr REST API Explorer

To see Flickr’s API explorer in action, you can experiment with requesting a user’s public photos from Flickr. Follow these steps to use the flickr.people.getPublicPhotos method in the API explorer:

  1. Go to this link in your browser: https://www.flickr.com/services/api/explore/flickr.people.getPublicPhotos
    You should see Flickr’s App Garden, showing a form with input fields for the arguments required in the request for public photos.
  2. Enter the following values:
    • user_id: Paste in the Flickr user ID of the user whose public photos you wish to retrieve. A user ID is a string of characters with an @ sign in the middle. For example, use your own Flickr user ID or feel free to use mine: 31065906@N08.
    • Leave all the optional arguments empty.
    • Output: Select XML (REST). This is the default option.
    • Authentication: Select Do not sign call. (Flickr does not require authentication for this particular API request.)
  3. Click Call Method.
  4. Scroll down to see the response. The API explorer returns the response body, and a copy of the request URL.

This screenshot shows the input fields for the flickr.people.getPublicPhotos call:

Flickr API Explorer

To find all the methods available in Flickr’s API explorer, go to this web page:  https://www.flickr.com/services/api/

The methods are listed down the right-hand side of the page. For example, to find the method you’ve used earlier:

  • Click the link on the words flickr.people.getPublicPhotos. You’ll see a documentation page about the getPublicPhotos method.
  • Scroll to the bottom, and click the link to the API Explorer for the method.

Twitter REST API Explorer

Twitter’s REST API requires user authentication for every request. The API explorer is especially useful in this case, because it takes care of the authentication plumbing for you. All you need to do is give the explorer permission to access Twitter’s data via your Twitter username. Twitter uses the OAuth 1.0 protocol to authenticate the user. In this case, you’re the user, because you’re using the API explorer. This will all become clear if you follow the steps below. 🙂

  1. Go to the Twitter website and sign in as usual. (You do need a Twitter account to try this exercise.)
  2. Go to the Twitter API explorer at Exploring the Twitter API.
  3. Click the dropdown arrow under Authentication and select OAuth 1.
  4. A popup window appears, titled Request Twitter permissions. If you can’t see it, scroll down the page a bit.
  5. Click Sign in with Twitter.
  6. A window appears, titled Authorize Apigee’s API Console to use your account?
  7. Click Authorize app.
  8. You should see a short-lived message saying that you’ll be redirected back to the app. Then you’ll find yourself back in the Twitter API explorer. Under Authentication, you’ll see Twitter-<username> where <username> is your Twitter handle. For example, for me it shows “Twitter-sarahmaddox”.
  9. Under Select an API method, you’ll see a list of methods – these are the things you can do with the API. Click /statuses/user_timeline.json in the first set of methods (next to one of the blue “GET” buttons).
  10. A new set of panels appears. In the Query panel (the smallish panel near the top of the window), scroll down until you can see the user_id and screen_name fields. They’re right at the bottom of the panel, and not immediately visible. In the screenshot below, I’ve already scrolled down within the Query panel.
  11. Enter a Twitter username and screen name. In this screenshot, I’ve entered my own Twitter ID:
    TwitterAPI explorer
  12. Click Send. (The red button near top right.)
  13. A short-lived red-flashing message appears, letting you know the app is working. Then the response appears. If you see a green 200 OK, that means everything went well.
  14. Scroll down to see the full response. It’s in JSON format. The top part of it looks like this (but there’s much more):
    Twitter API explorer

Various Google APIs

The Google APIs Explorer provides a GUI interface for many of the Google APIs, including the Calendar API, the Gmail API, and many more:

Google APIs Explorer

Happy exploring!

%d bloggers like this: