The Most Effective API Quick Start Guides, in 7 Examples Developers are notorious for always taking the “learn-by-doing” approach to learning. We often skim the API docs to get the basics, and then turn to our command line to start tinkering around with the code—with a bit of help from Google and Stack Overflow, of course. Turns out though, that learning-by-doing is the most effective way for our brains to absorb information. Neuroscientists call this “experiential learning,” and have shown that the neural connections in our brain are strengthened by these sort of mental exercises, which means we learn faster when we learn this way. So instead of pushing developers to simply RTFM, we should also be making it easier for them to jump in and learn how they learn best. That’s why some of the best API docs include “quick starts”—tutorials that guide developers through a single call to the API. The point is to show the user how to do the simplest thing possible in the least possible number of steps. The easier your API is to pick up and implement—the more people will take advantage of it. Quick start guides lower that barrier to entry, effectively marketing your API to the learn-by-doers (aka the majority of developers). What a quick start guide is — and why your API docs need one All quick start guides try to get a developer started with the API as soon as possible—but there aren’t any industry standards for how that can be achieved. Some API docs might provide you with a code-block that you can copy and paste into your command line, while others might guide you through the entire set-up of your dev environment. Here are the two most effective ways to “quick start” a developer, and what they achieve: Let them learn the basics with some language-agnostic commands that they can run immediately. This is usually done through curl or Postman and lets the developer get their feet wet, with no setup necessary. This is mostly to see what kind of responses certain queries yield, without having to dive into the nitty-gritty just yet. Shorten the time to first “hello world” (TTFHW) with things like SDKs, wrappers, or even packages with sample projects. These tools are paired with a tutorial that guides the developer through making the first call with everything in place to make the second, should they continue using the API. There are pluses and minuses to both approaches. The more steps involved in your quick start, the fewer developers will try their hand at it. On the other hand, the more specific a quick start guide is to a developer’s use case, the more likely they are to see its relevant value. Here are several examples of each kind of quick start guide, and why they’re effective: Let them learn the basics One code snippet, ctrl+c, ctrl+v. That’s pretty much the whole barrier to entry for this type of quick start. So a developer who’s still making their mind up about your API isn’t going to be discouraged because you’re making him download a bunch of packages just to get the gist of how yours works. A curl command can serve as your API’s selling point. For the developer who isn’t sure exactly what kind of response they’d be getting, they can jump in with no strings attached and check it out. 1. GitHub GitHub is famous for doing a lot of things right, and their “Getting Started” guide is no exception. They let you first test your setup—so that you don’t attribute an error message to a bad setup, and then they give you a basic GET to try out. The most useful part of this page is what comes after the curl commands. The devs at GitHub broke down everything that you might find in a response header, so you can understand what to expect. It’s the perfect pairing of simple, but thorough enough to get someone acquainted with the API. 2. Mailgun Email optimization tool, Mailgun does a great job keeping their quick start as simple as possible. They walk you through sending an email with this single curl command: Similar to GitHub, Mailgun provides a bit of elaboration on what this command will do. Instead of breaking down the responses, however, they explain what’s happening on their end, giving you a bit more than a surface-level understanding of how their API works. 3. Square One of the bigger players in the payments API space, Square, gives an overview of their product before giving you a step-by-step guide to making your first HTTPS request. This makes sure that the developers visiting the page are interested in the product’s functionality before they start trying their hand at the API calls. From there, they run the reader through Authentication, and give them this curl command: But the quick start guide doesn’t end there. After they get the reader acquainted with how the commands work, they run them through the same type of call, but with Python code. This lets the developer choose how in-depth they want to go, without scaring away some less-experienced developers. 4. Clearbit Clearbit has a slightly different approach to getting developers started with their API. Right on their API reference page, they have a button to “Run in Postman”—a tool that lets you try the HTTPS requests without having to set anything up or do any coding. Once you drop the API key into the header, you can practice calls to all three APIs to get a sense of what kind of data they’ll return. This approach is similar to the curl command in that there’s no setup necessary—but it lets developers try out more different types of calls before committing to this API. Shorten “Time to First Hello World” (TTFHW) All developers love themselves a well-built SDK. Instead of making them work from scratch, or downloading all the coding tools they need individually—they get a nice bundle of code-editing and version-control tools, some packaging tools, and even some analytics/performance tools. Quick start guides that include SDKs include some type of tutorial that helps them set up and get through one or several calls. The SDK for each API is going to be different, so we won’t go into the best practices now. But the presentation and accompanying tutorial is what convinces the developer that your SDK is worth the extra time. Here are some examples of companies that came up with really effective ways to get developers started. 5. Dropbox Dropbox takes a very conventional route to their quick start tutorial. The API lets devs save, share, and access their cloud storage, so they’ve built a single SDK for every popular language—which they make available in a tab next to the language-specific overview and documentation. Dropbox keeps their quick start guide simple. They let you try out two of their most popular requests: listing the contents of a folder, and uploading a file to your Dropbox. From there, you can understand the drift, and get a more in-depth understanding in the API reference that’s the next tab over. 6. Parse Parse is a “backend as a service” tool that helps developers build apps. They basically provide a backend for the developer so that they don’t need to worry about setting up system logging, a database, or SSL. Because of the complexity of their platform, they had to build out SDKs for all the most popular use-cases. So before you start on a tutorial, they run you through a series of questions to give you the most relevant option: Which API you’re interested in Which environment you’re using What operating system you’re using Whether you’ve started a project or not While many API docs make several assumptions when presenting SDKs, Parse makes sure that they only present you with an SDK that fits your use case. Once you’ve made your selection, they give you a specific SDK and a tutorial on how to get set up. Their quick start guide is supported by loads of examples in their API docs, and a huge community that can answer any questions that might crop up. All these resources are necessary for complex APIs that can be adjusted to serve a large variety of needs. 7. Auth0 Auth0 is an authentication tool for developers who don’t want to build Single Sign On from scratch. They have an official quick start guide in their documentation page, but they actually extend the quick start guide to their product’s homepage. Auth0’s homepage includes this dynamic sandbox for developers and non-developers: From this, you can see how you can adjust the variables on your sign-on page within this snippet. For product teams who have dealt with the stress of building secure sign-on options, this is a tempting option that’s presented as clearly as possible. On their actual documentation page, they provide SDKs for each popular language with supplementing tutorials, similar to Parse, as well as “sample packages” that give developers dummy data to practice with. Auth0 goes above and beyond to illustrate the simplicity of their API. Their sandbox showcases the functionality of the code to non-developers, but their in-depth SDK for each possible use-case lets a developer integrate the app in as few steps as possible. Go big or go home Your API docs need to be a resource that devs can turn back to, time and time again. But what gets them hooked in the first place is how easy it is to get off the ground. The “quick start” section of your docs is a great opportunity to get people tinkering and excited with what you’ve built. Done well, it saves developers a ton of work reading through the API reference library and tempts them to try their hand at some code, no strings attached.