Can clients get started with your APIs in fewer than 30 minutes?

By Robert Delwood

A Lead API Documentation Writer

(This is the second of a three-part series about Swagger. The other articles will be posted in upcoming weeks.)

Introduction

The concept of API documentation is simple, right? It’s a listing of all the calls and parameters, along with their descriptions. That describes an API reference guide. You ask, Isn’t that the point of API documentation? It might be, if that was all there was to it. The reference guide, which is just a listing of words and their descriptions, can be analogized with a dictionary. The fact is, you can’t learn a spoken language just from a dictionary, and you can’t learn a computer language from just API reference guide. In both cases there has to be more. There are, too.

The API reference guide is not a Getting Started

The API reference guide is the iconic document for our community. We see it as a complete reference with all the calls, parameters, caevots, and notes. The irony is that everyone expects that this guide alone is enough to use the API. I don’t know where that expectation came from. It’s not enough. Its a reference guide. It’s designed to explain individual calls and maybe systems, or groups of related calls that accomplish a task. While it’s required to have, and is good for what it does, it’s what it doesn’t do that’s important to note. What it doesn’t do is to tell users how to start using the API. The first step, however, isn’t getting a registration key. It’s telling the user what the API is even used for. This may sound remedial or patronizing, after all isn’t that why they’re there in the first place, to use your API? Not always. Maybe they’re looking around to find an API to use.

We like to think APIs are simple. For example, paste this URL into a browser. The returned JSON shows the list of the space station’s current crew.

http://api.open-notify.org/astros.json

All APIs should be this way. But they’re not. Try this one next:

https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY

Notice the URL now requires an access key (as seen by api_key=DEMO_KEY). While this API’s free, you would need a validated key to get full use of the API. How you get it needs to be explained. And so starts the complications.

We need Getting Starteds

There is a whole category of information that is related to setting up or preparing to use an API. How to get started is part of that category. Cleverly called Getting Started, these explain literally the first steps before anyone even makes an API call. As examples, most APIs are proprietary and require registration for an access key, some sites encrypt data, and others have some sort of installation. That fact that some API documentation is bad, or that the set up is so complicated doesn’t help matters.

Getting Starteds are completely overlooked documentation suites. All the focus is on the API reference guide. Think about it, though. If you can’t make a call, what good is the reference guide?

This helps make my point. eBay has what I consider a halfway great Getting Started. I did complete it in about ten minutes, and so graded them halfway between gods and mortals, a Pirithous if you would. In contrast, look at Google Maps or Best Buy (selected more or less arbitrarily among big companies), and I think it’ll take considerably longer.

Each of these three companies made trade offs. Google Maps and Best Buy are status quo companies in the API aspect. They put their time and resources into API reference guides. It was clear what the call syntaxes should be. What wasn’t clear was how to make a call, much less how to make the first call. The clarity of the reference guide was the trade off of a better Getting Started. For example, with Google Maps I had to make three assumptions, including guessing if this was even the right API for me, but none of that stopped them from trying to extort money from me. But why do you have to assume at all? These are technical writing documents and nothing should be guessed at.

eBay is the opposite. They are an evolved company in the API aspect, putting their time and resources into a Getting Started. I was able to make a first call within a few minutes, almost exactly like that said. Where I ran into trouble was making the second call. Their API reference didn’t explain it well (I wish they had more examples in their parameter descriptions).

If I had to choose between the two extremes, I would rather be able to make a call than not. You thought about it a moment again, but if you can’t make a call, what good is the reference guide? The truth is, with a minimal API reference you’ll be able to figure out the syntax, if only through trial and error. It wouldn’t be a good experience but you’d probably do it. No, I’m not advocating this. I am advocating that we don’t have to decide between the two, we need to do them both.

The 30 Minute Limit

Exercise #2 was rigged. I knew what was going to happen ahead of time. We’re going to change this now. You’re going to try to show that I’m wrong about all of this.

I’m guessing you don’t do it, something between the C and D answers. The point is, the getting started documents are largely ignored. So why is that? I can think of three reasons.

First, there is just too much emphasis on the API reference guide. This is the one document everyone knows about. Search YouTube.com for API documentation, and while there is a surprising number of hits, without fail they concentrate on the reference guide. Very few even mention other documents, and then, only in passing.

Second is Swagger. Swagger has done the API documentation writing community a disservice. They made API writing easier but ignores the documentation suite. The tools do not properly support technical writing by not having a real editing tool, encouraging short descriptions of calls and parameters, and not being able to customize the user interface. New writers accept these limitations as normal.

Third is that we’re not training our replacements properly. New writers come from technical writer ranks, and not the programmer ranks. While that’s not necessarily bad, everyone has to understand, that immediately puts them at a disadvantage. As the grognards and the experienced programmer writers retire (that’s assuming there’s a grognard even around) we’re not training these writers. They may have on the job training, akin to being thrown into the pool to learn how to swim, but not being programmers, miss important aspects.

It’s not difficult to write a getting started. Pick a single path that is the quickest way to get to a call. That means the following:

Single path: I know there may be several ways to make a call, direct to browser, cURL, Postman, or installing your SDK, or so on. Just pick one. I like the ones with the fewest downloads, or installations.

Quickest way: Aim for fewer than five minutes. You should have already looked at ten APIs from because of this article alone, so you know that some APIs getting starteds take longer than others. Be one of those others. If it can’t be done in five minutes, you might need to talk to your development team. This falls in line with one of my rules: You’re your clients advocate, not your developer’s. That, and it might take some of your time to figure out that quickest path. It’s better for you to spend that time than them. They’ll probably just give up.

Go step-by-step. Literally write down every step. A good product virtually writes itself. You’ll see the problems with a bad one.

So what can we do right now to fix this? Stop writing API reference guides. Not entirely, of course, but stop that writing, and immediately write a getting started guide. Aim to have your audience write two calls, one Get and one non-Get, in fewer than five minutes. I keep saying two calls for a reason. One call can be easy, typically a Get call, and more so if your product doesn’t use an access token. Earlier you made a call about the space station in a single copy and paste. Making a second call may not be as easy. You may need to get an access token, and perhaps pass information in header and/or body. If you can show them how to do that, or better yet, show them figure out the second call themselves, they can then make any call. Writing the Getting Started will let you be aware of the problems they may have. You may find out your own product isn’t that easy to use. The process doesn’t have to end there. Show them how to process JSON, or walk them through simple use cases from start to finish.

Summary

The API documentation writing community has to band together and demand better products. I advocate an approach I call If it’s not broken, then break it. That means, write your software companies relentlessly with bugs, things you don’t like, and things you do like. They can ignore some of us but not all of us. Post aggressively on forums about the things you’d like to see. This adds to the marketplace of ideas. If the companies ignore this, they risk the open source community to come up with their own products.