Search results

API getting started

Last updated: Mar 30, 2019

Following the product overview section, you usually have a “Getting started” section that details the first steps users need to start using the API. This section often includes the whole process from beginning to end, compressed as simply as possible.

Purpose of the product overview

The Getting Started topic is somewhat like the typical Hello World tutorial in developer documentation, but with an API. The tutorial holds a user’s hand from start to finish in producing the simplest possible output with the system. For Hello World tutorials, the simplest output might just be a message that says “Hello World.” For an API, it might be a successful response from the most basic request.

Getting started tutorials are like Hello World tutorials.
Think of getting started tutorials as a kind of Hello World tutorial with the API. How long would it take for a developer to get the simplest possible response using your API?

Both Hello World tutorials and Getting Started tutorials share the same goal: to show a user how to use a framework, API, or some other system to get the simplest and easiest result, so they get a end-to-end sense of how it works.

As an example, you could take a common, basic use case for your API and show how to construct a request, as well as what response returns. If a developer can make that call successfully, he or she can probably be successful with the other calls too.

The Getting Started tutorial might involve the following:

  • Signing up for an account
  • Getting API keys
  • Making a request
  • Evaluating the response
Getting started
The Getting started tutorial usually walks users through the process from beginning to end but in a compressed, simple way

Put a link to your Getting Started tutorial on your documentation homepage. Make it as easy as possible for developers to use the API to get some result. If this means using pre-provisioned accounts or setup configurations, consider doing so.

Run in Postman button

In your Getting Started tutorial, consider including a Run in Postman button. (Postman is a REST API GUI client that we explored earlier in Submit requests through Postman.) If you have your API endpoints integrated with Postman, you can export your Postman collections as a widget to embed in an HTML page.

The Run in Postman button provides a button that, when clicked, imports your API info into Postman so users can run calls using the Postman client. As such, the Run in Postman button provides a way to import the interactive, try-it-out API explorer for your endpoints into a web page.

To try out Run in Postman, you can either import an OpenAPI spec into Postman or enter your API information manually. Then see the Postman docs on how to Create the Run in Postman button.

You can see the many demos of Run in Postman here. Many of these demos are listed in Postman’s API Network.

Postman API network
Postman API network

Here’s a demo of Run in Postman using the OpenWeatherMap API’s weather endpoint (which we worked with in earlier tutorials):

When you click the button, you should be prompted to open the collection in a Postman client:

Options to open the Postman collection
Options to open the Postman collection

Postman provides a powerful REST API client that many developers are familiar with. It allows users to customize the API key and parameters and save those values. Although Postman doesn’t provide the in-browser experience to try out calls as with Swagger UI, in many ways the Postman client is more useful because it lets users configure and save the calls they make. Postman is what internal developers often use to save and store API calls as they test and explore the functionality.

Especially if your users are already familiar with Postman, Run in Postman is a good option to provide (especially as one option of many for users to try out your API) because it allows users to easily generate the needed code to make requests in practically any language. It gives users a jumping off point where they can build on your information to create more detailed and customized calls.

If you don’t already have a “Try it out” feature in your docs, the Run in Postman button gives you this interactivity in an easy way, without requiring you to sacrifice the single source of truth for your docs.

The downside is that your parameter and endpoint descriptions don’t get pulled into Postman. Additionally, if users are unfamiliar with Postman, they may struggle a bit to understand how to use it. In contrast, the “Try it out” editors that run directly in the browser tend to be more straightforward and do a better job integrating documentation.

Samples of Getting Started Topics

Here are a few sample Getting Started topics in APIs. If you compare the various Getting Started sections, you’ll see that some are detailed and some are high-level and brief. In general, the more you can hold the developer’s hand, the better. However, the tutorial should still be brief and not simply redundant with the other documentation. The key is that you show the user the beginning-to-end, full process for working with the API.


Paypal getting started tutorial
Paypal getting started tutorial

Paypal’s getting started tutorial contains quite a bit of detail, starting with authorization, requests, and other details before making the first call. Although not so brief, this level of details helps orient users with the information they need. The format is clean and easy to follow.


Paypal getting started tutorial
Twitter getting started

Twitter’s getting started page has several getting started sections for different development goals. The text is concise and easy to follow. The tutorial links frequently to other documentation for more details. In the need for brevity, you might need to follow this same strategy — being brief and linking out to other pages that have more detail.

Parse Server

Parse Server getting started
Parse Server getting started

The Parse Server tutorial provides a fair amount of detail and handholding through the various steps. For the more detailed steps on connecting your app and running the server elsewhere, the tutorial links out to more information.


Parse Server getting started
Adsense getting started

The Adsense tutorial separates out some foundational prerequisites for getting started on the platform. After you get set up, it then provides a “quick start tutorial.” The tutorial walks users through a simple scenario from end to end, helping them get a sense of the product and its capabilities.


Aeris getting started tutorial
Aeris getting started tutorial

The Aeris weather getting started provides information for setting up an application and then making a request in one of several popular languages. While showing code in specific languages is undoubtedly more helpful for programmers coding in those languages, the code samples might be irrelevant to other users (e.g., Java devs might find the Python code irrelevant and vice versa). Focusing in a specific language is often a tradeoff.

Watson and IBM Cloud

Watson and IBM Cloud getting started tutorial
Watson and IBM Cloud getting started tutorial

The Watson and IBM Cloud getting started tutorial lists three steps. It’s not an end-to-end getting started tutorial, though. It just gets the user started in selecting a service for your project. At the end, you start to code using the Watson Dashboard. Ideally, a getting started tutorial should help a user see some tangible output, but whether that’s possible or not depends on your API.

Activity with getting started tutorials

With the open-source project you identified, identify the getting started tutorial. Then answer the following questions:

  1. Does the API have a getting started tutorial?
  2. Does the getting-started tutorial walk you through an end-to-end scenario?
  3. Can you follow all the steps in the getting started tutorial successfully?
  4. How long does the getting started tutorial take to complete?
  5. In an attempt to simplify the instruction and keep it brief, does the documentation make assumptions about your technical level and familiarity with the domain?
Buy me a coffeeBuy me a coffee
Stay updated
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,500+ subscribers. (See email archive here.)

77% Complete

77/157 pages complete. Only 80 more pages to go.