Getting started tutorial
Following the API 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
- Run in Postman button
- Samples of API overviews
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 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 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
- Evaluating the 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. (Postman is a REST API GUI client that we explored earlier in Submit requests through Postman.) If you have your API endpoints integrated in 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.
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:
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. This 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), as 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 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 redundant with the other 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 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. 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.
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 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.
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. Focusing in a specific language is often a tradeoff.
Watson and IBM Cloud
The Watson and IBM Cloud getting started tutorial lists 3 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.
42/108 pages complete. Only 66 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.