{"id":630,"date":"2017-01-26T00:48:58","date_gmt":"2017-01-26T00:48:58","guid":{"rendered":"https:\/\/readmeprd.wpenginepowered.com\/?p=630"},"modified":"2024-08-08T16:08:48","modified_gmt":"2024-08-08T21:08:48","slug":"the-most-effective-api-quickstarts-in-8-examples","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/the-most-effective-api-quickstarts-in-8-examples","title":{"rendered":"The Most Effective API Quick Start Guides, in 7 Examples"},"content":{"rendered":"\n

Developers are notorious for always taking the \u201clearn-by-doing\u201d approach to learning.<\/p>\n\n\n\n

We often skim the API docs to get the basics, and then turn to our command line to start tinkering around with the code\u2014with a bit of help from Google and Stack Overflow, of course.<\/p>\n\n\n\n

Turns out though, that learning-by-doing is the most effective way for our brains to absorb information. Neuroscientists call this \u201cexperiential learning,\u201d and have shown that the neural connections<\/a> in our brain are strengthened by these sort of mental exercises, which means we learn faster when we learn this way.<\/p>\n\n\n\n

So instead of pushing developers to simply RTFM<\/a>, 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 \u201cquick starts\u201d\u2014tutorials 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.<\/strong><\/p>\n\n\n\n

The easier your API is to pick up and implement\u2014the 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).<\/p>\n\n\n\n

What a quick start guide is \u2014 and why your API docs need one<\/h2>\n\n\n\n

All quick start guides try to get a developer started with the API as soon as possible\u2014but 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.<\/p>\n\n\n\n

Here are the two most effective ways to \u201cquick start\u201d a developer, and what they achieve:<\/p>\n\n\n\n

    \n
  1. Let them learn the basics<\/strong> with some language-agnostic commands that they can run immediately. This is usually done through curl or Postman<\/a> 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.<\/li>\n\n\n\n
  2. Shorten the time to first \u201chello world\u201d (TTFHW)<\/a><\/strong> 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.<\/li>\n<\/ol>\n\n\n\n

    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.<\/p>\n\n\n\n

    Here are several examples of each kind of quick start guide, and why they’re effective:<\/p>\n\n\n\n

    Let them learn the basics<\/h2>\n\n\n\n

    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.<\/p>\n\n\n\n

    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.<\/p>\n\n\n\n

    1. GitHub<\/strong><\/h3>\n\n\n\n

    GitHub is famous for doing a lot of things right, and their \u201cGetting Started\u201d<\/a> guide is no exception. They let you first test your setup\u2014so that you don’t attribute an error message to a bad setup, and then they give you a basic GET to try out.<\/p>\n\n\n\n

    \"Screenshot<\/figure>\n\n\n\n

    The most useful part of this page is what comes after the curl commands.<\/p>\n\n\n\n

    \"Detail<\/figure>\n\n\n\n

    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.<\/p>\n\n\n\n

    2. Mailgun<\/strong><\/h3>\n\n\n\n

    Email optimization tool, Mailgun does a great job keeping their quick start<\/a> as simple as possible. They walk you through sending an email with this single curl command:<\/p>\n\n\n\n

    \"Mailgun's<\/figure>\n\n\n\n

    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.<\/p>\n\n\n\n

    3. Square<\/strong><\/h3>\n\n\n\n

    One of the bigger players in the payments API space<\/a>, Square, gives an overview of their product before giving you a step-by-step guide to making your first HTTPS request.<\/p>\n\n\n\n

    \"Screenshot<\/figure>\n\n\n\n

    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:<\/p>\n\n\n\n

    \"Detail<\/figure>\n\n\n\n

    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.<\/p>\n\n\n\n

    4. Clearbit<\/strong><\/h3>\n\n\n\n

    Clearbit<\/a> has a slightly different approach to getting developers started with their API. Right on their API reference page, they have a button to \u201cRun in Postman\u201d\u2014a tool that lets you try the HTTPS<\/a> requests without having to set anything up or do any coding.<\/p>\n\n\n\n

    \"Screenshot<\/figure>\n\n\n\n

    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.<\/p>\n\n\n\n

    \"Screenshot<\/figure>\n\n\n\n

    This approach is similar to the curl command in that there’s no setup necessary\u2014but it lets developers try out more different types of calls before committing to this API.<\/p>\n\n\n\n

    Shorten \u201cTime to First Hello World\u201d (TTFHW)<\/h2>\n\n\n\n

    All developers love themselves a well-built SDK. Instead of making them work from scratch, or downloading all the coding tools they need individually\u2014they 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.<\/p>\n\n\n\n

    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.<\/p>\n\n\n\n

    5. Dropbox<\/strong><\/h3>\n\n\n\n

    Dropbox takes a very conventional route to their quick start tutorial<\/a>. The API lets devs save, share, and access their cloud storage, so they’ve built a single SDK for every popular language\u2014which they make available in a tab next to the language-specific overview and documentation.<\/p>\n\n\n\n

    \"Dropbox's<\/figure>\n\n\n\n
    \"Example<\/figure>\n\n\n\n
    \"Full<\/figure>\n\n\n\n

    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.<\/p>\n\n\n\n

    6. Parse<\/strong><\/h3>\n\n\n\n

    Parse is a \u201cbackend as a service\u201d tool that helps developers build apps. They basically provide a backend<\/a> for the developer so that they don’t need to worry about setting up system logging, a database, or SSL.<\/p>\n\n\n\n

    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:<\/p>\n\n\n\n