Category Archives: APIs

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. 🙂

API Technical Writing – tcworld India 2016

This week I attended tcworld India 2016 in Bangalore. What an amazing experience! I’ll write a summary of the conference soon. First, here are some notes on a session that I presented at the conference: “Introduction to API Technical Writing”.

The slides for my presentation are available on SlideShare: Introduction to API Technical Writing (slides).

Presentation overview:

  • An introduction to APIs.
  • An overview of the role of API technical writer, and of our audience – the developers who need our documentation to use
  • APIs in their applications.
  • A technical writer’s view of the types of API we might document.
  • Demos of 2 APIs that you can play with yourself.
  • The components of API documentation.
  • Examples of good and popular API documentation.
  • Working with engineers.
  • Tips on getting started as an API technical writer.
  • Why API technical writing is a good field to be in.

API Technical WritingThank you so much to everyone who attended the talk. The room was packed to overflowing. After the session, and indeed throughout the conference, people came up to discuss the field of API technical writing and to show me things they were working on. A number of conference attendees do API documentation as part of their role, and it was very interesting to see the variety of requirements even in this niche within a niche: API documentation within the technical writing profession.

For the next tworld India, I think it’d be a good idea to have a panel discussion on API documentation. We could invite 3 or 4 people working on different types of APIs, and within different environments (such as internal versus external documentation, or integrations).

How a developer accesses an API

This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?

The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:

  • Where to download the API and other tools you need.
  • Where to get your API key or other required app credentials.
  • A hello world app or some basic sample code.

During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.

Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)

Calling a REST API or other web service API

As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.

Importing a library-based API

For a library-based API, you need to import a library of code or binary functions into your development project (your application). Then you can use the functions and objects in your code. When using a JavaScript API, for example, you get the API by including a <script> element in your HTML page. The <script> element loads the library supplied by the API. In this case, the download of the API happens every time the browser loads the HTML page. This type of API is sometimes referred to as “client side”, because it runs in the browser on the user’s computer. To see an example, take a look at the documentation for the Google Maps JavaScript API, which describes the <script> element needed to load the API library.

For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.

Downloading a flower

Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. 🙂

How a developer accesses an API

3 essentials in an API get-started guide

Developers may need to hook their application up to an API so that the app can get data from somewhere, or share data with another app, or request a service such as displaying a message to the user. The getting-started guide is one of the most important parts of an API documentation set. Often the developer can find their way around an API with just the getting-started guide and the reference documentation.

A getting-started guide for an API (Application Programming Interface) helps a developer get their application interacting with the API.

At a minimum, a getting-started guide tells developers how to:

  1. Download any tools required, such as an SDK (Software Development Kit) or a code library.
  2. Get any necessary authentication credentials for their app, such as an API key.
  3. Fire up a hello world app. This is a program that does very little. Typically, it prints “hello world” to a web page, a screen, or the developer console. The purpose of a hello world app is to make sure the developer has all the tools and configuration required before they can start developing.

Here are some examples of API getting-started guides:

Interestingly, if you examine API documentation on the Web, you’ll come across a few different types of guides called “getting-started guides” or “quick-start guides”. It’s an overloaded doc type. 🙂 For example, some quick-start guides take the form of a tutorial, leading developers through a simple use case for the API. The resulting app is something more than a hello world app, and is useful for developers who need information about what the API does (typical use cases) as well as the authentication and setup steps.

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?

%d bloggers like this: