Building great APIs, part IV: Great developer support

This is part four in our "Golden Rules for Great APIs" series (see links at the end of the article), and it tackles a subject which is very easy to pay lip service to but very difficult to deliver on:

Provide great developer support!

This is a challenging topic since great support is hard to pin down and has that “you know it when we see it, but kind of hard to define” type of quality. When trying to pin it down, it would be easy to put together a list of buzzwords (timely, friendly, to the point, etc.) and leave it at that. Beyond this, we also typically think of support as purely the human interactions which we experience when requesting support. However, beyond these, potentially it helps to think of API support first and foremost from the point of view of the customer (the developer in this case):

As a user of this API, support is everything that enables me to get my job done, to be successful, to ship…

In other words, what developers ultimately care about is shipping the Apps in as painless and efficient a manner as possible. Often there might also be more than one API involved – making it doubly important that each one has a quick effective pathway to success. From a support perspective, great APIs need to:

• Allow developers to make rapid progress – i.e., “it took me 15mins to start pulling results and make magic happen in my App – awesome!”
• Have self-service, easily navigable help documentation when things aren’t quite working – i.e. “Couldn’t figure it out immediately, but I searched the help and these two forum posts solved it – no need to call anybody!”
• And… lastly, If these fail, they have knowledgable, friendly and responsive support team members who can fill in the gaps in a timely manner – i.e. “Joe from support got back to me right away and solved my problem.”

Although the last item is what one might most obviously think about as being called support, in fact all of these form a hierarchy of helping the developer reach their end-goal shipping. Being faced with situation where the only resolution is a phone call is a blocker, having to wait 3 days for an email from support is a blocker. Clearly the human factor in point 3 – how friendly and accessible are support team members are – is important in people’s overall perception of the API, but even if the support team is outstanding, having to call them time and time again just to inch forward on an implementation will still leave a poor impression (not to mention wear out your support team!).

While we try to give an overview here, there is a wealth of good material out there on how to support API Developers – API Evangelist is a great starting point. Also see Brandon West‘s great summary on Support/Docs and what elements are needed.

Types of Support

Before digging deeper into concrete aspects, it’s important to acknowledge that for APIs there are generally two types of support needed for an API:

• Development time.
• Runtime.

Discussions of support tend to focus on the former: helping developers write their applications initially and complete their integration. Certainly this is a crucial step and where the learning curve is the steepest. However, once integrated, using an API means an ongoing relationship – outages, slowness, changes etc. in the API potentially affect integrated applications at runtime when the developer using the API is not expecting issues. API outages may take down dependent applications, so it is critical to ensure support is available to respond to runtime issues as well as integration time issues.

It may also be the case that different teams in your organization will be responsible for different elements of support – typically run-time support will require an ops-team. We won’t cover this extensively in this post, but it needs to be planned for (and the post on API Management covers some of the tools and processes they may need).

The Non-Human Elements of Support

As mentioned in the opening, support is not just about the human element in the loop (team members responding to queries) but the overall experience of “getting things done” with the API. Given that a developer’s main objective is to get a job done quickly and painlessly, the more can be achieved without waiting around for human intervention the better.

The following items should be high on the list:

• Concise Descriptive High Level Overview Documentation: a brief but informative description of what the API actually does – what kind of applications can be written and what kind of use cases are covered. This isn’t typically required by the developer once the API is being used by anger, but it is very important early one when developers are deciding whether to dig in or not.
• Clear Comprehensive Reference Documentation: high level is not enough however if there is a real job to be done and the next critical item is a complete reference guide to the functionality on offer. This is important since it forms an essential description of the toolset available and helps the developer find exactly the right method for what they are trying to achieve.
• Interactive / Sandbox Tools: A relatively new but important addition is the provision, where possible, of some form of interactive sandbox that allows developers to write trial calls to an API and see the result. There are tools available such as Swagger (which 3scale supports automatically), I/O Docs and Apigee Console. Each of these has a slightly different take on how to structure and maintain the sandbox but all serve essentially the same function: enabling the testing of calls without having to write code.
• Code Samples: a further, very powerful, type of documentation (see highly regarded APIs such as Stripe and Twilio for example) is the use of code samples – small snippets or even extensive downloadable libraries that illustrate how to achieve a particular use-case. These can save developers a lot of time and help make the abstract potential of the API appear to be a lot more concrete. Code samples take a lot of effort to prepare but are genuinely worth the effort many times over in helping developers help themselves.
• Forums, Comment Threads and Discussion: unless your API is operating in a very controlled environment where third party comments are unwelcome or not possible, forums and comments are a great way to make the user community come alive and participate in support. Having message boards on which users can pose public questions and either the support team or other users answer them both enables people to engage and keeps answers to questions building up in a shared knowledge-base in a way email does not. Forums clearly have their own cost in terms of moderation and a commitment has to be made to provide timely responses, but the community engagement possible will likely repay this cost quickly.
• Inspiration as well as education: Developers will often come to an API with pre-conceived ideas of how it will work (based on what they’ve seen elsewhere) and may then churn through with this mindset. So providing examples and snippets about what is possible (shortcuts, special features, deviations from the norm) can both save frustration and potentially enable them to do things they did not know where possible at the outset.

Human Elements of Support

However good your self-service information is, Humans are still needed in the loop. Support roles in technology-driven companies are sometimes perceived as unglamorous or “second class” to mainline engineering or marketing/sales. It is hard to know where this bias comes from, but in the API World allowing this perception to hold is both very wrong and probably a recipe for failure. In addition to the many general reasons why a powerful commitment to service as a culture brings great benefits (Tony Hsei’s Zappos story is inspirational), for APIs valuing the support function is even more important:

• API Support is requires coding skills: it will generally need individuals who are both able to communicate well and able to write code in order to genuinely help developers – finding talented people in this regard is highly challenging.
• API Support requires complex out of the box thinking: APIs are effectively a “Swiss Army Knife” of functions that enable a wide range of use cases – and support team members will have to be adept at discerning what the developer is trying to achieve and understand how to deliver it.
• It is an 80:20 world (or is it 90:10?): it is likely that the most (20%) successful integrations of your API will drive very large volumes (80%) of the business that will flow through the API – making sure these integrations run smoothly is a hugely critical task. Further, the support team needs to be able to determine which integrations will be most important and ensure these succeed, whilst providing a still friendly service to the remainder.
• Tech influence in purchasing is strong: When it comes to APIs, more so than with other types of IT products, technical staff (developers) typically have a large role in deciding which solution to go with since they will be in charge of execution. A big factor in the way they will swing is likely the level of trust that they place in the capabilities of the support organization.

As a result, API support teams are an integral part of customer success and ultimately also part of the marketing/sales process. Great support generates more success and more happy customer stories.

Taken together, all this means that it is very important to find the right type of team members to serve in these roles:

• Passionate: about your company, the API and helping customers succeed.
• Technically Competent: able to engage developers as a peers.
• Curious and Interested: in what developers are doing with the API and learning more about the potential of the API.
• Attention to Detail and disciplined: able to follow up and ensure things are carried out when they need to be.

Working with customers on App rollouts using an API can, in many cases, be more exciting and varied than working in the core engineering organization. So hopefully thoughtful, passionate people in your organization will step forward!

It may also be that a blend of different roles is needed – from a more standard technical support role to something more akin to an “API Evangelist”. The later is a new role which is emerging that typically involves more than standard customer support and tends to add in: public speaking about the API, attending hack/coding events to represent the company and potentially also going further in terms of thought leadership about technology / what can be done with the APIs. It may also be that everybody on the support team takes on somewhat of this role. Again see API Evangelist and other web resources for some great resources on this topic.

Additional Factors

The pointers so far have been relatively “support” specific, but there are a number of other factors to strongly consider that significantly affect how API support is executed within your organization:

• Good API Design: APIs which follow standard conventions for whichever world they are from (SOAP, REST etc.) are more intuitive to developers and require less head-scratching before progress can be made. This in turn increases the amount of self-service success that developers can experience – reducing human support load. While there may be perfectly good reasons for breaking standard conventions, in places where there is a choice “ease of use” should likely be one of the decision factors.
• API Stability and versioning: related to the first point – one of the most confusing elements of most APIs is when multiple versions of the API exist in parallel, when new versions are released and it becomes unclear which version is in play at a given time. Long term thinking, good communication and stability on the API go a long way to reducing support burden.
• The Right People: already mentioned in the previous section, ultimately the human element will always play a role in the success of the API. The more dedicated, passionate and effective the support team, the better the results will be – and their enthusiasm will add an infectious desire on the part of developers to work with your platform: possibly better than your best marketing in promoting uptake.
• Community Support: when resources for support are limited, a powerful effect (if it can be created) is for users of the API to support each other via (for example) forum posts and tweets which answer support questions before your support team can reach them. This kind of dynamic is wonderful when it occurs but it can be difficult to kick start – in our experience, at least 1-2 dedicated team members are needed to set the tone and always be willing to dig in to issues which the community cannot answer. Community advocates can typically act as a “multiplier/amplifier,” but it is rare that they can carry the entire burden.

The Value of Great Support – your best API Marketing Channel

Great support has a cost – both in tools/content and in hiring great team members to interact with users. Often this cost seems hard to justify since it seems outwardly to be more of a cost-center than anything else.

The impact of great support for an API typically plays out in one of the core business metrics that likely needs to be tracked: conversion rate from interested developer to live application/customer or something similar. This metric is often treated as secondary to the raw number of sign-ups for the API but it shouldn’t be – it is arguably even more important. At a more fine-grained level:

• How many implementations are successful?
• How long did they take from sign-up to go live? Could this time have been made shorter with better support?
• How much “talk time” is needed with support team members? – could some of that have been avoided with better documentation (which in turn would reduce recurring cost to the support team).

The second dimension in which great support pays off is positive public sentiment about the API and word of mouth. The following are example tweets about some of the best-known APIs (these are both from today – searching for other top APIs quickly also produces numerous results):

and the rather timely tweet:

Although it is hard to gauge the exact impact of this, it is very clear that such public advocacy is one of the most powerful forms of validation for adoption of your solution. Just as Rackspace focused on “Fanatical Support”, commitment to excellent support for your API can reap rewards.

Conclusions

It is hard to imagine a truly great API with poor support. While it’s possible that an API may be very intuitive for developers and technical help required is minimal – at least a minimal engagement from the API provider is needed to set the tone, smooth over corners and build confidence in the platform.

The best APIs truly excel at support and put in place both automated and human mechanisms to make sure developers can succeed. Ultimately, support for the API needs to be a first-class citizen in the planning process and not an after-thought or a cost center to be minimized.

Coming up

In the next post, we’ll tackle the last of the 6 golden rules – scalability and reliability: an API that’s great in all other dimension but performs poorly falls at the last hurdle!