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

Continued on page 4.

4. Establish Trust

From the moment visitors come to an API provider's portal to begin their discovery process, the portal is sending out signals about the trustworthiness of the API and its provider. These signals, both tangible and intangible, often work in conjunction with an API portal's ability to educate users and help them feel that they've made the best choice.

Users visiting an API portal are likely to be in one of three stages of their API journey, and they probably have questions when working at any of those stages:

  1. Discovery, which is the stage where users have a business problem and are looking to learn about you, what your API does, and how can it help solve their problems and how much it costs
  2. Where users, having decided your API can address their needs, are ready to start, and now need to understand the patterns and best practices that will help them succeed with your API
  3. When developers who are consuming and building with the API have run into difficulties and now need to understand how to properly call the API to get the results they're looking for

You need to ensure the content presented on the site helps users go through your DX, while the site architecture acts as a road map for users to find answers to their questions.

We've discussed why having a clear UVP on the landing page is important, and how this addresses the first set of questions from the discovery stage. But the landing page can't do it all alone. Think about the navigation. Do the menus intuitively point users to the location that answers their questions? In addition to menus, is there text with Calls to Action (CTAs) on the landing page to guide them?

Dropbox was highlighted earlier in our discussion of landing pages, but it also does a great job of presenting users with very simple, clear navigation and, as shown in figure 20 below, a set of text-based CTAs. Note that the text promises answers to the user's common questions, which we've already mentioned.

Figure 31: Dropbox's portal navigation is simple and clean, addressing the developer's concerns during Stages Two and Three. The company addresses these users' concerns by providing separate links to documentation, guides (where they can get started with the API) and support if users currently consuming the API have more detailed questions.

Figure 31: Dropbox's portal navigation is simple and clean, addressing the developer's concerns during Stages Two and Three. The company addresses these users' concerns by providing separate links to documentation, guides (where they can get started with the API) and support if users currently consuming the API have more detailed questions.

Figure 32: Dropbox sprinkles a number of CTAs throughout its landing page.

Figure 32: Dropbox sprinkles a number of CTAs throughout its landing page.

For users wanting to get started quickly, Dropbox has numerous links to its own SDKs as well as to those provided by its developer community. Developers wanting to dive right into working with the API can click any of the links to various API resources or the API explorer. And users looking to connect with the developer community can head straight to the online forum that Dropbox runs.

Transparency, Trust and Proactive Developer Communications

Being upfront with your API's status and providing a standing record of any changes you've made or that you plan on making are forms of transparency that build trust. GitHub's portal does an impressive job of this by dedicating the bottom quarter of the portal's home page to a record of the latest updates to the API. Developers can also subscribe to be notified of updates through email. Facebook offers a great changelog that not only lists changes to the API separated by version but also features a section that identifies which of those changes will cause existing integrations with previous versions of the API to break (often referred to in the API economy as "breaking changes"). Another cool touch is the table that lists when each version of the API was introduced and it's expected end-of-life date.

Figure 33: Facebook provides a valuable changelog page like this one for its Graph API. The page reflects the API's different versions, lists which changes break integrations, and also links to upgrade tools.

Figure 33: Facebook provides a valuable changelog page like this one for its Graph API. The page reflects the API's different versions, lists which changes break integrations, and also links to upgrade tools.

An API monitor or dashboard helps users by alerting them to any issues the API may be having. For example, this can help developers when they're troubleshooting issues because the alert will tell them that a problem actually originated with the API instead of with their code. Mailchimp has a server status page that shows the last seven days' worth of uptime of their 40+ servers. The company also runs a separate Twitter account that tweets the status of the Mailchimp service and embeds the most recent of those tweets alongside the status dashboard in the Mailchimp developer portal. Another good example is Stripe's dashboard, which includes a very visual presentation of its various services' performance over the last 90 days.

Where Are You and Your API Going?

A dedicated roadmap is an excellent way for you to communicate plans about your API. It keeps developers in the know regarding what features are in the works and notifies them of any changes that might affect their integrations. This gives developers a nice long runway to adjust to your roadmap, especially if involves any breaking changes to the API. As mentioned earlier, breaking changes are changes to the API's technical contract that could crash or "break" existing applications that consume the API. Collaboration hub platform provider Slack presents a nice roadmap in the form of a Trello board. This roadmap shows the platform's upcoming features listed as app user experience improvements and API updates.

We discussed the Terms of Service (ToS) earlier, but it also plays a part in establishing trust with potential users. Having a clear and easily located ToS shows users that you have nothing to hide and it helps them understand what to expect from their relationship with you while at the same time asserting what behavior is expected of developers (and yes, developers should always play by the rules).

Developer Engagement

A final and very important piece in establishing trust with users is for you to display an understanding of developer relations and outreach. There are numerous ways to achieve this from devoting resources to maintaining active developer forums, producing blog content to keep developers up to date on your API, and meeting your audience where they "hang out," through events and webinars. Each of these pieces helps to build an active and engaged ecosystem that serves as proof points that drive interest in your API. This gives users the impression that both the API and your business will be around for the long term.

Github's API developer forums involve Github's community manager, moderators, and members of the developer community answering questions, and they are very engaged. This serves as a proof point when it comes to Github's commitment to its API as a product. Likewise, when developers see a community that's actively engaged with an API provider, it can serve as evidence that the API is both well-established and well-supported.

Amazon Web Services (AWS) blog Is hard to top as a model for an active developer blog. It's updated several times a week by a team of developers and offers news, product updates, tutorials, training webinars, and more.

Figure 34: The AWS blog is known for frequent updates of useful content that engages the reader.

Figure 34: The AWS blog is known for frequent updates of useful content that engages the reader.

In addition to its blog, AWS also has a landing page that lists its past events and training webinars with the ability to access their recordings in an on-demand fashion. Beyond offering great content to the developer, a page like this shows a provider's commitment to connecting with its audience and bringing its developer community together. The AWS team also notifies its developer community (the developers that are registered to use its APIs plus other developers who have signed up for other Amazon-related events and materials) of upcoming events and webinars via email.

Continued on page 6.

 

Comments (0)