Best Practices: How to Engage Developers with a World-Class API Portal

Continued from page 2.

2. Help Developers To Start Working with the API Quickly

You've managed to convey the value of your API, described what it can do, and explained how it can solve a user's problems. If all has gone correctly, the potential user will want to try out the API. You need to be able to onboard developers to your APIs with as little friction as possible. This critical part of the developer experience (DX) is the so-called Time to Hello API; essentially the API version of Time To Hello World. Here the goal is to give your users the feeling of success quickly and with minimal effort on their part. If you can make your portal as self-serviceable as possible, your users' DX will be a much better one as their exploration of your API begins.

Several factors can accelerate and simplify the Time To Hello API, including:

  • Having a self-service signup and registration process
  • Provisioning the necessary API credentials (e.g., API key) as a part of that process
  • Offering "Getting Started" guides for securely developing applications with your API
  • In-depth tutorials built around sample use-cases
  • Tooling, such as SDKs and code samples, both covering all of the relevant programming languages. For example, if the API is best consumed with mobile applications, then the SDKs and code samples should cover popular mobile platforms like iOS and Android, and the languages that serve them (e.g. Objective C, Swift, Java, and Kotlin)

Onboarding

The key to successful onboarding is to eliminate any obstacle (either time or task) that stands between your API and potential developers. Avoid anything that complicates or slows their efforts to try your API. For this reason, your self-registration process should require as few steps as possible. NASA's API portal does a great job by requiring only a name and email on the API key request form. Once developers press submit, they're shown their API key immediately and given a sample API parameter that's prepopulated with their API key for cutting and pasting, either into the source code of an application or into a cURL command for calling NASA's API from a command line (see Figure 7, below)

Figure 7: Onboarding with only the essentials, NASA's API portal asks the bare minimum and then immediately gets developers started.

Figure 7: Onboarding with only the essentials, NASA's API portal asks the bare minimum and then immediately gets developers started.

Stripe, an online payment processing company, goes one step further by providing users with a test API key, so they can try the API in a non-production mode without ever having to log in or register.

Figure 8: Stripe opens its sandbox to decision-makers with a test API key that allows users to sample the API without having to register first.

Figure 8: Stripe opens its sandbox to decision-makers with a test API key that allows users to sample the API without having to register first.

Educational Content and Tutorials

Once developers register, most will naturally look for a Getting Started guide. Think of this part of your documentation as the launchpad. Such a guide not only helps take developers through the important steps needed to begin using the API, but it also acts as an assurance that they're doing things correctly. Peace of mind, even in this simple way, raises a customer's confidence that your products and services are the best choice. While the Getting Started guide should spell out the individual steps, it doesn't necessarily have to go into each step's gory details. The goal is to give the developer an end-to-end understanding of how best to work with your API, and how to do so in a reasonable amount of time (again, keeping Time to Hello API in mind). The guide provides crucial information but doesn't bog down the user with extraneous details. Then, you can link to other pages that go into more depth on particular topics.

At its most basic level, a Getting Started guide often includes:

  • Instructions on creating an account
  • Obtaining an API key
  • Setting up authentication and authorization
  • Making an API request (often referred to as "calling the API")
  • Evaluating the response

As mentioned earlier, your guide should also cover common use cases for your API. Doing so might seem outside the mandate for sticking to essential information. But remember that the developer is still exploring and is open to learning new perspectives in addition to steps, facts, and procedures. GitHub, for example, does a good job of offering a basic introductory guide in addition to specific guides for tasks that are common to its API users.

Figure 9: GitHub's Development Guides page rewards developers immediately by answering the initial question that's most frequently asked, ''I want to roll up my sleeves and get started. How do I do that?''

Figure 9: GitHub's Development Guides page rewards developers immediately by answering the initial question that's most frequently asked, "I want to roll up my sleeves and get started. How do I do that?"

GitHub also presents its users with Learning Lab, an interesting and innovative approach to Getting Started material for its API. Learning Lab is a bot-based educational environment that takes users through a series of immersive virtual "labs" in which they get to play an active role. Instead of a text or video tutorial, Learning Lab is an app that lets users participate while they're learning. We would love to see more providers using the opportunities offered by this type of educational material.

One piece of critical documentation that providers often forget is a guide that shows how to use an API securely. Developers need much more than a single section that describes the authorization and authentication workflow for your API(s). You need to present the challenges your users will meet when they're looking to develop secure code and you should stress the importance of security-first coding nevertheless. Clever, a developer of education system integration technology, makes sure to explain its security practices and offers security recommendations for each product. Why is a focus on security so important? According to a study by High Tech Bridge, a global provider of web and mobile Application Security Testing (AST) services, for mobile backends:

  • 88% of API and web services used in the mobile backend contain exploitable vulnerabilities that allow access to sensitive or even confidential data;
  • 69% of API and web services used in the mobile backend have insufficient anti-automation mechanisms or protections [e.g. web application firewalls (WAFs)] against common web attacks.

Gartner, an IT research firm, has predicted that by 2022, APIs will be the most favored attack vector for hackers looking to breach enterprise Web applications. Educating users on security best practices when consuming an API should be table stakes for all API providers. Okta is another provider that shows its commitment to security by offering developers a Getting Started guide on API endpoint protection.

If users have a successful onboarding experience and receive a basic understanding of how to use your API, there's a much greater likelihood that they'll dive right into integrating it with their applications. At some point, they may run into a problem they can't solve by reviewing the API reference alone. This is when you need to have comprehensive tutorials available. Tutorials differ from guides by instructing developers on how to perform specific actions at a much greater level of detail. Remember, tutorials should solve user problems instead of showing off functionality. If you've been paying attention to the queries made by your user community, you'll see how they often have the same misunderstandings and troubles with similar tasks. These difficulties are the ideal candidates for in-depth tutorials.

Twilio, a communication tools company, offers a great set of tutorials for its APIs. Each tutorial takes users step-by-step through the process and offers a number of excellent features that are useful to anyone following along. Twilio provides its tutorials in multiple programming languages, and users can access each through a drop-down menu at the start of the individual page. As they proceed, the page displays the sample code in a persistent window on the right side of the screen. The code is specific to the SDK for the users' preferred language, and they're given the code for the two most recent versions of the SDK.

Figure 10: Twilio gives users everything they need at one time to speed and simplify learning, including instructions and sample code. Twilio even offers two tabs of sample code for two different versions of the API as shown in the screenshot, top right.

Figure 10: Twilio gives users everything they need at one time to speed and simplify learning, including instructions and sample code. Twilio even offers two tabs of sample code for two different versions of the API as shown in the screenshot, top right.

As users scroll through the tutorial's steps, the code in the right-hand pane changes automatically to keep relevant with the narrative in view (in the center pane). This very nice feature not only saves a click, but also ensures that the step they're viewing displays the proper code. The code window has two buttons: one that lets the users copy the entire block of code and the other (shown in the screenshot, top right) that opens the code sample in GitHub.

As for the content itself, the Twilio tutorials are thorough and include a ton of links for use as a glossary as well as information about any additional tools developers may need to finish their work.

Another great idea that we don't see often enough is the use of video tutorials. Along with providing an explanation of the steps involved, video allows users to sit at your side as you show them how to use the API. Kairos, a provider of a face recognition API, has an excellent (and brief) video tutorial that explains how users can make their first Kairos API request with Postman. (Postman is the leading graphical API query tool).

Tooling

An important part of making developers productive with your API is to meet them where they are in terms of technology and language choice. A good portal provides resources in the form of SDKs and sample code in languages that are appropriate for developers. Therefore, if the API is appropriate for mobile applications, you might want to offer SDKs for iOS (e.g., Objective-C and Swift) and Android (e.g., Java and Kotlin). But if the API is more appropriate for server-driven applications, then you should give them SDKs for server-side platforms, such as Python, Node.js, and PHP.

SDKs are sometimes referred to as "libraries", "clients", or "client tooling." Providing SDKs is a very important part of developer engagement because it lets developers work in the programming language they're most comfortable with and flattens their learning curve when they start to implement the API in their applications. The SDK simplifies working with APIs by abstracting cross-cutting concerns (such as authorization, authentication, logging, and data transfer), thereby improving developer productivity, especially when creating new applications.

Sample code can take two forms. The first is the code snippet. These snippets, which are easy to cut and paste into a developer's source code, are often sprinkled throughout the API reference. The second takes the form of a sample project that shows users how to complete a non-trivial task. Make sure the sample code is bug-free, because developers may actually use it in third-party implementations. Additionally, the code, replete with comments, should highlight any best practices that developers ought to follow when interacting with the API. In some cases, the sample code is offered as open-source through Github as Ping Identity has done (shown in Figure 11 below). By offering sample application code through a code repository like Github, developers can not only copy the code directly into their own code repositories, they can easily fork the code, or even improve it by submitting pull requests to the API provider.

Figure 11: Ping Identity, a provider of secure digital identity solutions, includes sample code on GitHub that users can modify and use.

Figure 11: Ping Identity, a provider of secure digital identity solutions, includes sample code on GitHub that users can modify and use.

Continued on page 4.

 

Comments (0)