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

Continued from page 5.

5. Support

Eventually, your users will be comfortable using your API and will begin to develop their apps. In the beginning, you can expect them to refer to the API reference on a regular basis. But along the way, they're bound to need help with their niche problems that are not addressed by your portal (or for some reason, cannot be found). This is where your portal should aspire to provide two types of support — that which is provided by your team, and that which is provided by the community.

Team Support

From an overall standpoint, the Google Maps platform support page is one of the best around.

Figure 35. Google Maps Platform Support offers developers a comprehensive resource.

Figure 35. Google Maps Platform Support offers developers a comprehensive resource.

The Google Maps support page links to numerous support channels (including a detailed FAQ) and to nearly 20 topics on StackOverflow.com (not owned or run by Google) covering the various APIs within Google's platform. Users can report bugs or request features, and they can contact the support team directly. Google is not the only API provider that makes use of the forums on StackOverflow (often called just "Stack" by developers). StackOverflow is one of the largest, if not the largest, independent developer communities on the Web. By meeting developers where they already are, API providers like Google make it easier for those developers to engage with them.

A nice feature on the Google Maps section for contacting support is an estimate of the expected response times, based on the severity level of the issue. Google Maps also does a great job of listing the various Google groups a user can join to stay informed of any updates to the platform. An example would be google-maps-api-tech-notify, which is the home for all technical updates to Google Maps APIs and web services (receiving ~ten messages per year).

Earlier we touched on how blogs can help build trust, but they're also a good way to provide additional support by publishing tutorials. One company that's mastered using its blog as a user resource is Clarifai, a visual recognition AI company. The Clarifai blog shows us how to use a blog for support by having a section dedicated to API tutorials.

The use of an online chat widget is another way for an API provider to have its team offer real-time support to users. Some providers will have the chat widget staffed by a human while others make use of a chatbot. Clarifai, a visual recognition AI company, does both.

Figure 36: Clarifai support teams with an AI support bot dubbed Clairbot.

Figure 36: Clarifai support teams with an AI support bot dubbed Clairbot.

Even some of the most well-known API providers make use of off-site channels to offer support to their users. Square uses its developer Twitter account to frequently make announcements both big and small, link to articles and tutorials about the API and even show some personality. Square also invites developers to join its Slack channel where they can connect with other developers in the Square community.

One implementation of Slack we'd like to see is for providers to allow access to the community's Slack channel directly from the developer portal user interface. This can be through a Slack button that would open the Slack channel via a widget when clicked. We haven't seen this on an API portal yet (let us know if you have seen one). But, it has been implemented in GraphQL Editor. The figure below shows this in action.

Figure 37: Clicking the icon on the upper left (1) will take users to the GraphQL Editor Slack channel web page (2).

Figure 37: Clicking the icon on the upper left (1) will take users to the GraphQL Editor Slack channel web page (2).

One way of offering passive support that is useful to API consumers and helps make the portal more of a self-service offering is to have an analytics page or pages where users can track their usage of the API.

Figure 38: Clearbit has a user dashboard where API usage over the various time periods is measured.

Figure 38: Clearbit has a user dashboard where API usage over the various time periods is measured.

This is a handy way to let developers know if they're approaching their monthly limit of calls. The dashboard also has a tab where users can view their billing information. All of these touches mean users can easily find the information they need in one place.

Community Support

API portals also serve as a way to bring the developer community together to pool experiences. Through this central support, area members can offer each other assistance for any common issues that arise. The most common method seen in portals is the community forum. GitHub's API Development and Support Forum is a very active forum featuring on average 30 threads per week. Many of these threads contain responses from members of the community that don't work for Github thereby increasing the number of avenues developers have for getting help outside of GitHub's own staff.

Facebook has a system in place where community members can report any bugs they encounter. Here, users can see if a bug they're dealing with has been reported and whether Facebook is working on it.

Figure 39: Facebook developers can report bugs, monitor the status of reported bugs, and check if bugs have been previously reported.

Figure 39: Facebook developers can report bugs, monitor the status of reported bugs, and check if bugs have been previously reported.

As mentioned earlier, some providers will leverage the developer Q&A website StackOverflow to handle technical questions about their API. Again, Google has nearly 20 tags for the Google Maps platform. While the portal is clear that Google does not run the site, members of the Google Maps Platform team actually monitor the tags and offer help along with community members.

Offering different avenues of support, meeting developers where they engage versus always requiring them to come to you, provides value that goes beyond good customer service. That flexibility shows how serious you are about treating your API as a product, helps improve the overall DX when developers consume an API, and also serves to foster a community around the API. Smart providers also use their support channels as a feedback loop by tracking the kinds of questions being asked and using that information to improve not only their portal but the API and their service as a whole.

Your Perfect API Portal

If this looks like a daunting list, it is (and we'll no doubt be adding to it). In today's climate, APIs are a serious and essential part of a business strategy. Your API developer portal (as well as any unofficial extensions of it) should reflect as much and show that your organization treats its APIs like products that you're making a significant investment into and that you stand behind.

It's important to keep in mind that users will be coming to your portal at various stages of their API journeys. So, the content it offers, its design, and the degree to which it encourages engagement should reflect your commitment to helping them along, every step of the way. This means answering beginner's questions about what the API is (even what an API is), the value it provides, and how it can help solve a user's problems. Success means helping users both start with the API right away and providing them with the guidance and best practices they need to create some short-term wins. And once they've become a consumer of the API, the portal gives them the support they need while acting as a gateway to an active ecosystem.

Of course, some APIs may be intentionally trivial, and a full-blown portal could be unwarranted. But for any organization that truly wants to scale its business through its API ecosystem, the criteria listed in this paper should be thought of as a standard designed to maximize the satisfaction and therefore the loyalty of your target developer community.

An API Strategy Blueprint

The topic of developer engagement is a major component of our four-stage blueprint that organizations should follow in order to maximize their chances of success in the API economy (for an in-depth discussion of this blueprint, be sure to read our whitepaper on API Strategy Essentials, developed in partnership with MuleSoft).

Figure 40: The blueprint for API economy success is broken into four critical areas, none of which can be overlooked by organizations hoping to lead competitors in their fields. The four-stages run concurrently (are not necessarily sequential); iteration with an eye towards improvement is constant, and measurement against quantifiable objectives within each stage is always ongoing.

Figure 40: The blueprint for API economy success is broken into four critical areas, none of which can be overlooked by organizations hoping to lead competitors in their fields. The four-stages run concurrently (are not necessarily sequential); iteration with an eye towards improvement is constant, and measurement against quantifiable objectives within each stage is always ongoing.

The first stage of the blueprint — Establish Digital Strategy — has almost nothing specific to do with API strategy. Instead, it focuses on aligning stakeholders around an understanding of the organization's core capabilities and competencies and how best to bring them to market as digital offerings that drive great business outcomes and amazing end-to-end customer experiences.

The same approach applies to whether the customer is external or internal to the organization. Understanding and Organizing Successful API Ecosystems is a key component of this first stage and requires organizations to think well beyond their four walls in terms of what a market-leading end-to-end customer experience is, and the ecosystem that's necessary to make it happen.

The second stage of the blueprint — Align Culture and Organization — is about getting the entire organization to think differently about what it takes to deliver those great end-to-end customer experiences. Even if it means reorganizing the company. This also means looking at those experiences as finished assemblies of discrete capabilities, some parts of which are sourced internally, some of which can be sourced externally, but all of which are organizationally managed and engaged as individual services that are carefully choreographed, with the help of APIs, to produce the final outcome.

As you can see, so far, the blueprint has been focused on areas that are more about the business, organization, and culture than they are about putting any technology in place. But this is where the third stage comes into play, covering both the core API platform as well as any adjacent technologies that are necessary to install, secure, manage, and measure the API-driven fabric that will technologically enable your business strategy.

With the first three stages being about getting the business strategy, organization, and tech in place, the fourth stage is about customer-centrically engaging your ecosystem in ways that are wholly consistent with the desired business outcomes, experiences, and values set forth in those other stages. Engaging developers with the best in class API developer portal, the subject of this paper, is critical to succeeding in this fourth stage of the API Strategy Blueprint.

 

Comments (0)