Top 25 API onboarding experiences

Effective technical onboarding gives new users the tools and knowledge to be successful. In this post, we’ll look at 25 examples of resources that were developed to onboard new users to public APIs. These resources can be reused throughout the developer’s lifecycle as they become aware of new features and expand to new use cases, and they can also be used for onboarding new team members who are learning about your technology.

Prioritizing technical onboarding

If you’re an API producer who wants to do a better job of onboarding your consumers, how important is it when there are other priorities competing for your attention? When it comes to API onboarding, it’s important to make sure it’s seamless, easy, and efficient.

Here are some reasons to invest in a smooth technical onboarding experience:

• Faster time to value: A smoother onboarding experience gives developers a faster time to value that results in real downstream impacts, like higher conversion and retention rates for your API.
• Have a market differentiator: There are many reasons why developers choose to consume APIs, such as quality, convenience, and usability. Some of these criteria are table stakes that are expected from every API producer, but having an API that is easy to get started with is still a good way to stand out from the crowd.
• Increase productivity: Onboarding is not just for new users. Existing users rely on the same tools and resources to expand their knowledge for deeper integration and advanced use cases. Additionally, the onboarding resources you develop for public APIs are equally beneficial for teammates and collaborators who are consuming and integrating with your private and partner APIs.

In the 2022 Postman State of the API survey, respondents cited faster development times as a key factor in an organization’s decision to consume an API:

In the same survey, documentation and usability were both reported as being top factors in deciding to integrate with an API:

Even though other factors—like performance, security, and reliability—are ranked as more important when deciding to integrate with an API, they typically don’t come under full scrutiny until much later in the developer journey. If you don’t address friction early in the onboarding process, your pool of developers will dwindle before you can impress them with these other factors.

It’s no longer enough to simply provide an API that does the job. It costs time and money for developers to learn new technologies. Investing in technical onboarding addresses some of the most pressing leaks in your acquisition funnel or flywheel throughout the developer journey.

Insight into the developer experience

API producers, like your consumers, have a limited amount of time and resources. How do you know where to start? Knowing the common pain points developers encounter with your APIs helps you prioritize what needs to be done.

Here are some quantitative and qualitative ways to gain insight into the developer experience:

• Measure time to first call (TTFC): Pull the logs or run an experiment to see how long it takes a developer to make their first successful API call. On average, is it a few minutes, a few hours, or a few days? If the answer is significantly more than you expected, start here first.
• Exposure hours: As the API provider, you unfortunately have the “curse of knowledge,” which is the cognitive bias that makes it more difficult to communicate about a subject that you’re an expert in. Spend time with, or watch, developers as they learn how to use your APIs. You can also ask new team members to document their feedback with a fresh perspective so you can identify the gaps in onboarding.
• Optimize search: Perform a search audit within your developer portal, in addition to broader search engines, to ensure you’re optimizing for expected keywords. You should also take a look at the most popular pages by impressions in your docs and search terms that yield zero results.
• Ask them: Explicitly asking developers for their feedback can seem too obvious and daunting, but it yields immediate insights. This can involve structured usability testing with specific prompts for feedback. It can be accomplished with a brief survey sent to new and existing users, or it can be as quick as a few open-ended conversations with collaboration partners.

Once you understand the biggest pain points for your developers, you can prioritize what to do next.

Principles for more effective technical onboarding

Let’s look at shining examples of API onboarding, grouped by the following principles, for more effective technical onboarding.

1. Provide wayfinding
2. Address early blockers
3. Show advanced usage
4. Enable troubleshooting
5. Don’t forget about discovery
6. Delight your users

1. Provide wayfinding

Do not underestimate the importance of this one. The manner in which new information is organized and presented to new users is crucial. Some API producers organize resources by Postman teams, workspaces, collections, and folders to more clearly communicate information architecture to the user.

Navigation

New users may not be familiar with industry-specific terminology, the branded names of products and services, or your company’s history of mergers and acquisitions. Information that is clearly organized reduces cognitive load for new developers.

• Cisco is a company with a history of mergers and acquisitions that resulted in a breadth of technology under one roof. Their team profile shows workspaces organized by business, with each business managing a workspace teeming with their own collections. This level of abstraction allows users to focus only on the technology they’re exploring.

• Oracle is another company with independently managed businesses. If you’re looking for Oracle Hospitality APIs, that’s a far jump from Oracle Cloud APIs. Oracle is organized by team so each team can manage their workspaces independently.

• LinkedIn has more public APIs than you might expect. On their team profile page, you can browse workspaces organized by departments at LinkedIn. Each department publishes collections to their own workspace, making it easier for developers looking for a specific API.

Get started

• ArcGIS provides a guided tour of getting started with their APIs thorough documentation in the workspace. The collections are numerically listed to recommend an explicit order of operations.

• Infobip collections are organized in their public workspace by service, and each collection contains a prominent Get Started folder that directs the user’s attention to their first API calls.

• Mercedes-Benz collections are also organized in their public workspace by service, with workspace documentation directing users to “START HERE,” along with links to pre-requisites.

By experience level

• EasyPost maintains one primary collection with the top-level folders divided into Basics, Advanced, and Account Management, so users can self-select into experience level and role. The nested folders are then named by industry concepts.

By industry concepts

• Lob is another workspace that relies on one primary collection that contains industry concepts, which makes it easier for new users who are unfamiliar with terminology.

Even though proper organization and naming seems like a no-brainer, sometimes it’s tough for API producers to explain things effectively to new users, which is partially due to the “curse of knowledge.” The bias can be countered by following the recommendations described earlier for gaining insight into the developer experience.

2. Address early blockers

At the beginning, developers can give up because they’re stuck on authorization, or they don’t have the data or other pre-requisites in place to fully experience the API and understand the value it offers. Identifying these points of friction and easing the transition directly contributes to a faster time to first call and higher conversion rates.

• Amadeus has a folder called “Authorization,” which contains two API calls to programmatically set authorization tokens as Postman environment variables that can then be used throughout every request in the collection.

• Twitter has a pre-request script that runs prior to every request in their collection to sign and generate a token according to their specific authorization method.

• Belvo provides collections that contain the API calls required for different methods of authorization. Developers can step through each API call and see the scripts that set variables to then be reused in subsequent calls.

• Dwolla provides a sandbox collection and environment. Providing example data and a playground for experimentation can help developers learn more quickly. This is especially true when consumers are dealing with sensitive information or don’t want to incur costs while still learning what the API offers.

• Withings provides two environments for developers to toggle between cloud environments. They include secret variable types to obscure sensitive information and placeholder text for variables intended to be filled automatically by scripts that run after an API call.

3. Show advanced usage

Successfully making a first API call gives developers hope, and they can immediately wonder what else is possible. Outlining next steps to complete after their first call shows them the possibilities when they are hopefully most receptive, even if they’re not ready to pursue them right away.

• New Relic provides a collection that is filled with examples of GraphQL queries. They also include their GraphQL schema in the workspace, so if you’re not using their pre-formatted queries, you can enable auto-complete to write your own queries.

• Snowflake provides examples of requests and responses. If you’re not used to working with SQL databases, the examples cover various scenarios and demonstrate the structures of the request and response bodies.

• PingOne highlights use cases, outlining the specific sequence of API calls required to complete the task. Developers can step through each API call to better understand what’s happening at the API level, before choosing to integrate into their own applications with SDKs or APIs.

• UiPath is another workspace filled with use cases that outline various API workflows for automation, which are supported by thorough documentation in the folder descriptions.

• Dropbox provides an entire collection for team administrators, in addition to the standard API reference. The Dropbox Team Admin Workflows collection includes common admin tasks that allow potentially non-technical users to execute and walk through different API workflows.

• Mist Systems includes a collection to automate deployment and configuration of networks. Developers can execute these API workflows from the Collection Runner on demand, or they can integrate this functionality into their own applications.

4. Enable troubleshooting

Even in the best case scenarios, troubleshooting is part of the job for any developer. API producers have control over their API design and can directly control their API’s structure, response data, and response codes to make working with their APIs more predictable and intuitive. However, more can be done during onboarding to help developers while troubleshooting.

• Microsoft adds log statements in their scripts to validate permissions and authorization. This key piece of feedback is modest, but it provides visibility during authorization, which is one of the first challenges developers face when engaging with a new API.

• Feishu localized their workspace by providing a collection in Chinese for their customers. While most API producers link to their collection from their developer portal, Feishu also links to the collection from support and troubleshooting guides, as support engineers frequently use Postman Collections to reproduce issues for troubleshooting.

• Mulesoft hosts a workspace created by the community with contributions and input from community members. The workspace description contains updates about new releases, short videos to get started, and a section that addresses common errors where developers get stuck.

5. Don’t forget about discovery

It’s important for new and existing users to be able to find your collections, troubleshooting guides, and advanced use cases. You should optimize for search within your own developer portal and on major platforms, like the Postman API Network and others. You should also optimize for external search engines by making videos and blog posts that link to the relevant resources.

• DataStax is a NoSQL database built on Apache Cassandra. They named their collections and included adequate descriptions and summaries so that users searching for “cassandra” in Postman can find DataStax in the search results.

6. Delight your users

In most cases, the way to delight your users may not be something your developers are asking for, but it will make your API stand out from the competition. As the API producer, you are most intimately familiar with your API and its capabilities. It’s time to get creative or borrow ideas you’ve been wowed by in the past.

• Typeform has a secondary workspace for scripting API solutions to address specific customer needs. Since a picture is worth a thousand words, Typeform illustrated API workflows using Postman Flows so non-technical, business customers could visualize scripted solutions and learn about APIs interactively.

• ShipEngine has previously shared what they do to enhance developer onboarding. Their workspace includes a collection dedicated to walking new users through everything their API offers. Once you enter your sandbox API key, you can play with sample data. What’s more exciting than parsing JSON? Visualizing the JSON response. Data visualizations help new users understand the data returned from the server, and provide inspiration for future integrations.

Fix the leaks in your onboarding experience

In the 2022 Stack Overflow developer survey, 66% of professional developers have at least some influence over their organization’s decisions to purchase new technologies. While it is expected at senior-level positions, this helps explain why top-down purchasing decisions frequently fail without bottom-up developer adoption. Many organizations are therefore re-prioritizing documentation, onboarding, and developer experience.

For API producers, small investments in easing early friction points can make a big difference in a developer’s onboarding experience. Technical onboarding is not just about reducing the pain and suffering of developers in the early days, but also laying a solid foundation for the developer’s journey ahead.

Many of the superstar APIs covered in this post satisfy lots of these onboarding principles, but were only highlighted in one instance, so feel free to dig deeper into any particular API. You can also check out other APIs in the Postman API Network—and let us know about your favorite API onboarding experiences in the comments below.