Documenting getting started section
Following the 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 API 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.
Both Hello World tutorials and Getting started tutorials with APIs share the same goal: To show a user how to use your API to get the simplest and easiest result, so they get a sense of how it works and feel productive.
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
- Reviewing the endpoints available
- Calling a specific endpoint
- Evaluating a response
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, do so.
Run in Postman button
In your Getting Started tutorial, consider including a Run in Postman button. If you have your API endpoints integrated into Postman, you can export your Postman collections as a widget to embed in an HTML page. Postman is a REST API GUI client that we explored earlier in Submit requests through Postman. The Run in Postman button provides a button (labeled “Run in Postman”) that, when clicked, imports your API info into Postman so users can run calls using the Postman client. As such, this isn’t a full-fledged authoring tool but rather a way to import the interactive, try-it-out API explorer for your endpoints into a web page.
Here’s a demo of Run in Postman using the OpenWeatherMap API (
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 you don’t have the in-browser experience to try out calls, in many ways the Postman client is more useful. This is what 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), as it allows users to easily integrate your API into a client they can use. It gives them 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 API overviews
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 duplicate the regular documentation. The key is that you show the user the beginning to end full process in working with the API.
Paypal’s getting started tutorial contains quite a bit of detail, starting out with authorization, requests, and other details before making the first call. Although not so brief, this level of details surely helps orient users with the information they need. The format is clean and easy to follow.
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. This is usually the required strategy for getting started documentation. In the need for brevity, you have to link out to other pages that have more detail if the user needs it.
The Parse Server tutorial provides a good amount of detail and handholding through the various steps. For the more detailed steps of connecting your app and running the server elsewhere, the tutorial links out to more information.
The Adsense tutorial separates out some foundational prerequisites to getting started on the platform. After you get set up, it then provides a “quick start tutorial.” The information provides a user through a simple scenario from end to end, helping them get a sense of the product and its capabilities.
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 are irrelevant to other users. Ideally, code samples in a getting started tutorial might be more practical in a more language-agnostic framework, but if you have a good sense of user’s preferred languages, this approach can also work.
Watson and IBM Cloud
The Watson and IBM Cloud getting started lists 3 steps. It’s not an end-to-end getting started, 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 probably depends on your API.
38/101 pages complete. Only 63 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.