The success or failure of an API program is made by any number of things: The business value of the product or platform the API exposes, the ease of use of the API, or the number of ways it can be used. However, core to getting an API program right is delighting the developer by ensuring they have what they need to get their job done. At the heart of this effort are code samples, cookbooks and code tutorials that provide this knowledge by example. An excellent tutorial that decreases the time to get up and running with an API adds massive benefits for all concerned: To the API consumer and their development team, who’ll report on how good the API is and how easy it was to create their software integration, and also reputational value for the API provider themselves.

In this post we’ve taken a look at what makes a great API tutorial and what it takes to transfer your important API knowledge to your developer community. Like a story, which has a beginning, middle and end, an API tutorial has three distinct parts that help create a narrative on how to use an API:

• Setting the context;
• Exploring the details;
• Creating an application.

Throughout this post we’ll explore each of these parts in turn, citing several quality tutorials that you can model when constructing your own development guides.

Setting the Context

First and foremost, an API tutorial needs to reassure the reader that they are in the right place: visitors will likely understand what they need to accomplish functionally, but they may not yet be aware of the implications of integrating, and may not realize all your API has to offer.

For example, when choosing between the several Twitter APIs, a developer will need to make a choice between RESTful and streaming versions of the API. Alternatively, different APIs may have different security models and developers will need to be aware of what the impact of implementing one API over another may be.

Setting the context means devoting words to explaining to the reader the significance of creating an integration with an API, the skill level and provisioning status required, and what type of behaviors should be exhibited. Though this section won’t be exhaustive it still should include:

• Reinforcement of the subject matter: The tutorial should first reaffirm what the API does and what the developer can accomplish using the tutorial, with introduction of the core technological themes that will be introduced throughout, including programming language used, level of experience required, and security architecture. For example, this tutorial on Instagram exemplifies this point by keenly focusing the mind on the objective at hand;
• On-boarding requirements: The developer needs to know what is required to begin the tutorial. Do they need an API key? Is a user account involved? Is there a generic test account? Are there test card numbers, magic numbers a la the Twilio API? A sandbox with a complete data set? The questions are obviously specific to the API itself, but should be in the form of an easy-to-use checklist with links to both the resources that explain or expand on each point in the list or where the developer can act on the information provided. This Facebook API integration tutorial from Appery demonstrates well the kind of information required, with a series of screenshots describing how to register an application on Facebook (a pre-requisite to making an API call). The Braintree Getting Started guide also provides an excellent example;
• Runtime behaviors. Finally, the developer needs to know about any restrictions the API places on usage, such as limiting connections, consumption rates or throttling throughput. Providing this information prior to starting the tutorial will ensure developers understand how such behaviors will affect the design of their application and how to mitigate for them. Again, the tutorial does not need to cover the details in full but should provide links to more information.

Armed with this information the developer should have the necessary context to start exploring the API in detail.

Exploring the Details

With the context set it’s tempting to dive straight into creating a solution and letting developers understand the API from the source code of a built solution. However, if an API tutorial is going to achieve the goal of decreasing on-boarding time it needs to be inclusive and address the majority of audiences; not just those with skills and capabilities to decipher the important information from the code.

Rather, help users understand the code with a series of explanatory statements accompanied by code snippets which build up a complete picture of the API integration from nothing to a successful API call. The snippets need not amount to a working application, but if all were pulled together they should amount to something close to a working package, class or script (depending on the technology you’re using in the course of the tutorial) — building towards the complete solution discussed in the next section. Developers with more advanced skills are obviously welcome to skip the exploration section and go on to the completed solution.

The snippets themselves should exhibit a number of important characteristics:

• Explain what packages or libraries are involved: This will give the reader a better idea of what they need to understand alongside the API or allow them to correlate them with alternatives that they may already use. For example, if you use an OAuth package or library briefly explain why you chose that particular one and the benefits it delivers to developer;
• Dare to be verbose: The majority of developers write code and then refactor it to make it as terse as possible: Indeed, it’s one of the things that generally puts a smile on a developer’s face. However, such terseness can be challenging for junior developers to understand: Moreover, you will be talking to developers in the tutorial who aren’t experienced in the language it’s written in, but need to use it as a reference for implementing their application in their own language of choice (Whilst some API providers like Twilio can provide tutorials in several languages, not all API providers have the resources available to do this). For example, if a Python list comprehension can be understood better by more developers through verbose syntax consider doing so:

# Less Pythonistic but easier to understand for a non-Python developer

verbose_payments_list = list()

for payment in payments:
    If payment.amount > 0:
        payments_list.append(payment)

# More Pythonistic approach:

terse_payments_list = [payment for payment in payments if payment.amount > 0]

• Comments, comments, comments: Ensure the snippets contain lots of comments or are well annotated with text that clearly labels the intentions of your code. Continuing the theme of verbosity, comment more than you normally would to guide the reader through each step. A great is example is this Rails tutorial on Stripe integration, which clearly explains the purpose of each snippet.

Creating an Application

The final step in a building a great tutorial is bringing what you’ve explained to life by creating an application that a developer can actually run. Depending on the depth and detail of the solution itself this could be a simple code snippet, gist, GitHub project, or a Docker image that can be executed with minimal effort on the part of the developer. Naturally you are not going to walk through the entire solution in the tutorial, so make sure you summarize it with a few well chosen screenshots.

The bounds of your application are entirely dependent on your imagination, skills and the needs of your developer community, but you should look to do the following:

• Ensure it can be run in a minimal number of steps;
• Like the code snippets, insert a full range of comments and pointers that explain the significance of the implementation;
• Demonstrate a really compelling use case for your API.

Ensuring your application demonstrates these features will really help in concluding your tutorial and ensuring all the points you’ve raised are reinforced.

Final Thoughts

In this post we’ve explored what makes a great API tutorial and have highlighted the core themes that make it easy for your developer community to comprehend and digest the key information about your API.

It goes without saying that not every API tutorial will exhibit everything discussed here; however, if you focus on the points raised you should succeed in creating a compelling narrative that not only holds the reader’s interest but does meet the goal of decreasing the time it takes to on-board into your API program.