A brilliant, undiscovered app developer just logged into the front page for your API program (please don’t tell me you just emailed a PDF), and made their first successful call. They’re frustrated, feeling like they don’t understand what just happened, and generally just exhausted.

Hopes of impressing colleagues with a quick demo espousing the ease of adoption have been dashed. They are eagerly digging through your content trying to find a way to explain the value of what your API brings to his company.

…you might be about to lose out on the most serendipitous moment in your companies’ future. Developers you have never met might have the potential to change your future…but only if it’s easy to get started.

Getting started

The first thing your new API developer sees should be something along the lines of “Getting Started“, or “Quick start“. If the first thing they see is a catalog of URLs, with esoteric systemic descriptors…you may have already tipped the scales of effort versus reward. If a developer has to read every detail of your system in order to understand the first call, they’re likely to look for an easier alternative before they write any code, or even bother to register.

We’ve all heard the mantra that good developers are lazy developers. Developers want to feel like they have superhuman powers, while they sit in their underwear eating peanut butter. Maybe I’m stretching a stereotype here, but the truth is that if we make it easy to nail that first call in a few minutes, we’ve infused confidence that your API is going to work in their company.

Some great “Quick Start” examples:

Twilio SMS Quickstart: In a quick scroll, and a copy-paste, you can send an SMS. While not all APIs are that simple, this is a great example of a walk-through that a monkey could probably be trained to do it. The best part is, there are four more languages just one drop-down away.

Parse Quick Start Guide: Download a blank project, change one config line, and copy-paste a 7 line sample. You’ve saved an object to the cloud. Put on your Superman underoos, and open a fresh jar of peanut butter!

Concise errors

The worst feeling as a new developer trying out an API is seeing an error code with a generic description. Provisioning an account and keys, grinding through gritty documentation, building authentication code, and dancing through configuration, only to be met by “500 Server Error” (or worse yet, a nasty stacktrace) instantly feels like you are looking at a major waste of time.

Create consistent data in how your errors are presented.

• Every time a 40x or 50x range HTTP error is presented, there should be data to go along with it.
• The shape of that error data should be the same across all of your endpoints.

Study errors and exceptions

• Pay attention to what developers are tripping on the most.
• Provide extra ‘helper’ messages in the errors indicating what the easiest and most common fix should be.

Smooth out bumps in the road through error messaging

• This is often superior to adding more documentation, which developers are all too often going to miss.

For an example of an informative, consistent error, Twilio does a great job.

I have a fairly good idea that I need to authenticate before making this call. However if I hit the link provided in ‘more_info’, https://www.twilio.com/docs/errors/20003, I can see a more detailed explanation.

When errors aren’t enough

When it’s not easy to create good error messaging due to systemic constraints, reach out to your developers. I recently tried running a Twitter API sample on my Arduino Yun using Temboo. The error didn’t tell me a lot. I’m sure I just don’t know where to look yet. I figured I’d spend more time digging in and didn’t look at it for a day. Automagically, I get an email from Temboo’s head of product telling me what I did wrong, and how to fix it. Not only did I feel like I was being tended to, but now I’ve probably saved quite a bit of time on figuring this out myself.

SDK are easier than the REST

While developers love a clean, beautiful RESTful API, they love being able to download an SDK, make a reference, and make call without knowing how every underlying aspect works. Don’t get me wrong, before it goes out to the public, good developers will learn some of those details. That said, providing quick feedback on how your system works is the first priority.

Clearly, if you’re just getting started, writing SDKs for ten programming languages is going to be beyond your scale. However, if you are building a platform using a given language, and you are building an API-driven platform…you should have the best possible client for your API, and it should be available for download. This approach is the best way to start eating your own dog food.

If you are lucky, your clients will publish their clients, and you can provide links and support. If good abstractions aren’t coming your way on Github, perhaps you should challenge your staff to flex their polyglot muscles in your company’s next internal hackathon (yes, you should have those). Many developers have different language experience outside of their job, and are itching for a chance to stretch their skills.

A few great examples

Stripe: a great blend of in-house developed SDKs, and plenty of links to community-provided options for abstractions and plugins.

Dropbox: again, a handful of sanctioned languages, as well as links to “Others”, community and commercial options in languages not officially supported by SDKs.

TL;DR, what does this thing do?

Sometimes, business folks discover an API before developers do. Explain in simple, non-technical terms…what exactly is the business value in spending time on this integration?
In a world where even images have to be animated to grab attention, video is often the most efficient way to rapidly communicate value. While it make take a few paragraphs to describe your real value, you’ll find most of the content is rarely read.

Zapier: this is a great example of a quick ‘executive summary’ of how Zapier’s product works.

When video doesn’t quite makes sense, or you don’t have video production resources, an informative information flow with bulleted points can get the job done as well.

Yummly: while there are no flashy videos here, a solid responsive design with great photography and crisp bulleted content gets the point across very succinctly.

Adoption by Demo

If a developer can steal a code sample, fill in data that looks like something their customers would make, and show it to leadership, they can get buy-in faster than any other means. As an evangelist for your platform, this is the best way to teach your community’s developers to fish. Provide easy to adapt code samples that can rapidly be used to build demos.

If a developer has to convince their boss to take a week out of providing deliverables to make a simple demo, you’re probably not even in the running. If they can whip up a demo while eating lunch at their desk, you might be in the running for running a new piece of a budding star’s key strategic infrastructure.

It’s not you, it’s me

Maybe you’re in the minority. You work for an up and coming company with a rockstar API; people are integrating constantly, your support costs are low, and everyone is talking about how easy it was.

My guess is if you read this far, that’s probably not the case.

Success stories in APIs are fewer than you think, and it’s because many of the points in this post are not respected. Take a long hard look at the API you’re working on, and be honest with yourself and your colleagues.

If you’re already in a bad spot, and feeling hopeless, take material steps to change your momentum. Work on convincing your internal developers that there is a problem.

• Do your own demo in-house of how hard it is to get started in a lunch and learn or other technical venue. This might help shift the conversation toward broader concerns, instead of developers and product getting bogged down in the inconsequential details.
• Ask people with experience (that don’t draw a paycheck from your company) to give it a shot. Don’t help them, and ask for detailed notes, and/or record video to share with others.
• Listen. Talk to developers who have recently integrated and take copious notes.

Build the backlog for your API product based on real experiences. Study the behavior of the developers who want to use your core business value. Your software might provide serious value, but if it’s not easy to get started you might never have a chance to be considered.

Image Attribution:
http://mrwgifs.com/shot-to-the-head-blam-reaction-gif-in-scott-pilgrim-vs-the-world/
http://cheezburger.com/4067821824
http://www.seanet.com/~rod/images/raccoon.jpg

Please join in the discussion on this article over on Hacker News and reddit.

Last updated by Jason Harmon at October 18, 2013.