The API Developer Experience Baseline

You’ve invested in building an API and now you want developers to use it. Very few companies can get away with creating a successful API ecosystem on technical merit alone. You’ll need documentation, SDKs, sample apps, debugging tools and everything else that goes into a great “developer experience”.

Based on my experience of working with an array of different APIs, here is what I believe to be the baseline level of support structure anyone who is serious about their API program should implement. This is geared toward web service APIs, but the principles can be applied toward any set of developer tools.

This is A LOT of work and not every company will have the resources to do this. Strive to support as much of it as you can. I’m a proponent of owning the entire experience, but if that’s not feasible for your situation one of the many API infrastructure companies out there can help you achieve much of this.

If you’re in the midst of making plans to open up a new API, make sure to consider the cost of building related tooling so that it’s not neglected until just before release, or worse, after the API has been made public. Developer’s first impressions are so important.

Within each section the items are ordered by importance.

Contents

Documentation

API Reference

A method-by-method, endpoint-by-endpoint, property-by-property breakdown of every possible request and response to and from the API. For requests, all parameters should be listed and described with a clear designation for required parameters. For responses, a sample representation should be shown in each of the supported data formats along with a list of properties and their descriptions.

In addition to the detail for each endpoint, an overview should be provided that describes how requests are to be made, the response formats supported, how authentication works, and anything else required to understand the conversation happening between the developer’s app and your API.

If you use a complicated authentication scheme like OAuth, a through description of the user authorization process with descriptions of each request and response should be included.

Lastly, a list of all possible errors should be provided. The first thing a developer will do when they get an error is Google it so make sure they get a hit.

User Guide

A higher-level guide to using the API. This should be organized by task. If a task requires multiple API calls, an step-by-step walk-through for each task should be described. If a SDK is the primary interaction point with the API the examples in the User Guide should be demonstrated using each of the supported languages/frameworks, though it is helpful to show raw HTTP requests/responses or cURL examples as well.

If every API endpoint is a logical single unit-of-work, the User Guide could be combined with the API Reference.

Getting Started Tutorial

A simple example that is short enough to be easily copy and pasted into the dev’s editor and run with only minor modifications (like setting a variable to their API key). This is to prove that the API works in the shortest amount of time possible. Keep it simple, simple, simple. Provide a version for each of the supported SDKs.

SDK-specific Documentation

Include instructions for obtaining the SDK and any installation or configuration steps required to use it. Provide examples for making a sample request and demonstrate the best way to handle errant requests for that language or framework. Any other information only relevant a specific SDK (for instance, a class reference or auto-generated documentation) should also be included.

Sample Applications

Sample apps should be standalone applications that demonstrate common use cases that help deepen understanding of what the API provides or gives devs a starting point from which to build their app. They should be functional with only minimal configuration and easily run or deployed. If your API requires OAuth, provide a sample app demonstrating how to authorize users. If another sample app requires authentication to work, include the auth example in the same package. Provide sample apps in all of your SDK flavors, ideally with all the samples being available in all languages.

Sample apps should be written using the idioms of each language and framework they are written for. They should instantly feel familiar for a developer experienced with that language. This will prevent the focus from shifting to the quality of the code contained in the example and away from the task at hand.

Debugging and Information

Error Logs

If an error is generated in a request from a properly authenticated user log and make it available to view later. Indefinite history is not required, but the more the better. This is particularly useful if an app is making requests of other users and the log includes errors for federated requests as well (minus any sensitive customer data). The more visibility you give into errors the less support you’ll need to provide for mystery circumstances and the more data your support team will have when they do need to help a developer consuming the API.

Usage Logs and Limits

If your API charges for or restricts the amount of usage, provide a complete history of all requests that incur a ‘cost’. All information that was made available to the API client in the API response should be available in the logs.

For usage that is metered, provide an as-close-to-realtime-as-possible indication of the current amount of usage and the available amount remaining in the current time period.

OAuth Utilities

For APIs that use OAuth (and I haven’t met one yet that wouldn’t benefit from it), make it easy for the developer to get started more quickly by pre-populating access tokens that authorize their user account to access their own app. For a great example of this check out Twitter’s developer center.

API Console

Provide a tool to make requests to the API and see responses. These should be real API requests, just from a web-based interface. Apigee provides a free console you can embed.

Test API

For APIs with requests that have side effects, provide a mechanism to simulate a real request/response interaction with semantics as close to the real thing as possible. Be careful with code-based ‘test mode’ flags, those tend to get left on in production. Make it easy to distinguish between real and test requests without requiring too much ceremony to make test requests.

Provide the same level of tooling for all relevant tools in this list (logs, etc).

Billing History

For recurring or usage-based billing, provide a complete history of the payments made to the account. For APIs that don’t involve a lot of requests, make it easy to see which requests were associated with which charge. For APIs with a lot of requests, provide a usage breakdown by type for each payment. Give developers as much information as possible so they can adjust their usage to meet budget restrictions.

Reset Key

Someone will post their API key on GitHub, I guarantee it (I have many times). Don’t make the developer wait for support to have a new key generated. Make available a self-serve API key reset function. Make it scary, provide a lot of warning and confirmation. Just let them fix it themselves.

Multiple Credentials Management

Allowing API consumers to create and revoke multiple sets of credentials on demand is useful for a lot of cases, but one in particular worth mentioning: demos. When demoing how an app was built (which happens a lot with APIs) make it easy for your developers to create temporary credentials they can disable when the video is over without the pain of having to create and configure a separate account.

SDKs and Libraries

Common Language/Framework Support

Provide officially-supported SDKs for the most popular server-side languages and frameworks:

  • Java
  • JavaScript/Node.js
  • .NET
  • Python
  • PHP
  • Ruby

If it makes sense to request your API from a mobile device directly, provide iOS and Android SDKs. Mobile SDKs should also include authentication helpers/controls and common UI elements.

The list of frameworks and languages you should support is not static or globally applicable. Don’t ignore a big potential audience because you’re not familiar with it yourself.

SDKs should be in sync with the latest version of the API with updates being released in tandem with new API releases.

Proper Distribution

Each SDK should be distributed in the proper package manager for each langauge (npm, Maven, NuGet, pip, Pear, RubyGems).

The code for SDKs should be open source under a OSI-approved and popular license. Make it available on a public code hosting site, preferably GitHub. Accept community contributions and fix bugs quickly.

Idiomatic

Co-opting and paraphrasing the dictionary defintion: using, containing, or denoting expressions that are natural to a native developer. Appropriate to the style associated with a particular group.

Community Code

Provide a list of community-provided libraries, extensions and components for all languages and frameworks, even the officially supported ones.

Communication Channels

This section is more human than machine and usually involves a set of professions dedicated to it, so I’ll just hit on the key points.

API Status Dashboard

Set up a site outside of your API infrastructure to provide availability updates. If there is an outage, report it there first. Have it push to a RSS or Twitter feed. Provide email updates for individual incidents. Keep it updated regularly throughout an issue. If it’s not a consistently reliable source of information for up-to-date status you can expect repeated “are you down?” support emails.

Blog

Provide a blog for announcing new releases, demonstrating how to use features and explaining commonly-occuring issues and questions. A blog is also a good place to do a test run for new documentation or samples to gauge feedback.

Twitter

Communicate new blog posts, releases and availability issues via Twitter account (or multiple accounts if it makes sense). Be very attentive and quickly respond to developer questions. Treat it like a conversation, not a broadcast mechanism.

Changelog

Provide a list of recent changes to your API, SDKs or documentation. Heroku has a good example.

Forums

Provide a way for your users to talk to and help each other. This can cut down on your support load and also keep developers engaged. If you outsource this to a site like Stack Overflow, watch it VERY closely.

Email Support

If your API is free, this may be low priority for you. If it is paid, move this to the top of this section. Some problems can only be solved by looking at private code.

Future Must Haves

Here are a couple things that I think will be standard issue very soon:

  • Real-time (meaning no page refresh) logs and dashboard updates
  • In-place example code editing and running from within documentation
  • One-click sample app deployments to platform-as-a-service providers (like the Facebook/Heroku integration).

I’m sure I’ve missed something. What is a must have for you when working with an API?

Looking to hire more staff to build all of this for your API? Post a listing on API Jobs.