5 Reasons Why Developers are not Using your API

This post was originally published on the Nordic APIs blog as “5 Reasons Why Developers are not Using your API”. Have you launched your API and are you having a hard time understanding why it’s not being used as much as you anticipated? You’ve followed all the best practices, used all the latest technologies and have made sure it is always up and running. For some reason developers are not using your API, and its usage is not increasing over time.

Perhaps you forgot about the most important thing about your API: developers! Without developers that use your API and build new apps all the effort that you’ve put into it is meaningless. The question you should be asking yourself by now is why aren’t developers using your API more? Read on to get some possible answers.

1. Signup Difficulties #

Let’s start by analyzing how developers can start using your API after they find out about it. How long does it take them to get started? Ori Pekelman, a regular speaker at API events, created a rule that summarizes the best possible engagement between developers and your API. The 3:30:3 rule states that on the homepage of your API a developer should:

1. Understand in 3 seconds the purpose of your API.
2. Be able to identify the entry point in 30 seconds.
3. Be able to create an account, call the system, and use the result in under 3 minutes.

To be able to follow this rule you should treat your API as a product where developers are your target customers. First, focus on the homepage itself and what message it conveys to visitors. Developers should quickly understand the main feature your API is offering and how they can start using it.

The signup process should be as straightforward as possible, but you should be able to obtain all the information you need during this phase. A good strategy is to let developers sign up using a popular third-party service such as GitHub. Because GitHub uses an open authentication standard called OAuth, it’s easy to add a “Sign up with GitHub” button to your API portal. You’ll be able to quickly capture the developer name and email address without having them type anything.

After developers have signed up you should let them test your API as soon as possible.

2. No Sandbox to Play in #

A great way to let developers test your API without making them create a real account is to provide a sandbox that mimics all the features without manipulating any real information. The sandbox should be easy to deploy and reset by the developer whenever needed.

Developers will use the sandbox just like they would use your production API. The main difference is that usually the sandbox endpoint will have its own URL. The goal here is to let developers test against the sandbox and quickly migrate when they feel they’re ready to move to production.

A good option to provide a sandbox is to use some type of virtualization that lets your system quickly deploy a server that is ready to use by developers. There are several available options with varying levels of complexity:

• Using Vagrant with an image containing your API server and a fake data set. Vagrant quickly launches a VirtualBox machine that can easily be shut down and relaunched.
• Using Vagrant with a cloud hosting provider such as DigitalOcean. This option will make it even easier because you don’t have to deal with the servers yourself. There’s a great tutorial explaining how to get this setup and running.
• Using Docker to quickly launch a new API environment that developers can access. A way to do this is to use Fig which lets you launch an isolated environment using Docker.

Choose the option that best fits your needs, but remember that the sandbox is just a temporary environment where developers can experiment with the API. You should pre-populate any databases with a comprehensive data set and offer a quick and easy way to reset the sandbox whenever needed.

Google Adwords API follows this approach as they let developers make API calls against a test environment. Namecheap also offers a sandbox environment and encourages developers to use it before making calls against their production API.

3. Poor or Non-Existent Documentation #

A sandboxed API is only as good as its documentation. A good way to start is to provide a tour of the API features with sample code that developers can quickly try on the sandbox and see results.

You should also offer a complete API reference describing all the existing methods, their parameters and responses. Pay special attention to input and output formats (JSON, XML, etc.) and provide examples whenever possible.

There are two documentation sections where you should be more careful because they’re related with how end users of third-party apps will interact with your API and how their perception might be affected:

• Authorization: if you allow API consumers to act on behalf of users, you should provide concise documentation explaining exactly how the authorization works and what options are available to developers.
• Terms and conditions: you should clearly describe what you allow developers to do with your API and what your responsibilities are to end users. That article covers most of the options available for licensing your API even if you don’t have resources to hire a lawyer.

If your API offers any other feature that you consider important, you should definitely provide a separate, dedicated documentation section. The more you teach developers the better they understand what they can do with your API. Adding code examples for all calls, for instance, can help developers better understand how the API can be used.

4. Lack of Troubleshooting Resources #

After documentation, troubleshooting is the most important aspect you should worry about. More often than desired, an API behaves in a way that was not expected by the developer, and it should be easy to understand what really happened. You should provide a console where developers are able to inspect all the calls made to the API, their inputs and responses. With this information they’ll be able to identify what’s happening behind the scenes.

Even better is if you also maintain a forum or a way to let developers quickly get in touch with you and discuss problems happening with calls to the API. If you treat your API as a product, as I suggested above, you might find it more interesting to offer a support channel using a service like Zendesk or GetSatisfaction. These will allow you to make support requests public, resulting in a crowd-sourced knowledge base.

As a bonus, you could also offer a status page describing how different components of your API are performing over time. This will make it easy to debug possible connectivity related issues and avoid wasted time. Stashboard is an interesting open source project created by Twilio that will let you do this in an easy and effective way. If you don’t want to install anything, you can use a SaaS tool. Pingdom offers a monitoring and status board service that can be easily set up.

5. Poor Communication #

While being able to respond to possible support requests is important, you should also pay special attention to any outbound communication. Developers value companies that openly communicate about any changes, problems or improvements to the API.

You should communicate whenever any interesting event happens that affects the API usage in some way. Examples include new feature releases (with accompanying documentation changes), API status changes where one or more components become unavailable or slow, changes to the terms of service, and also any new third-party applications that have launched.

Several communication channels can be used: a developer focused mailing list with a reply-to address monitored by the support team, a specialized blog with a working RSS feed and open comments, and any other popular social media platform (e.g., Twitter). Not using social media, a mailing list, and your blog is a big mistake that you don’t want to make. You should understand your developer audience and use the most appropriate channels.

Conclusion #

By now you should know that developers are, in fact, the most important thing about your API. If you treat your API like a product and developers as your target customers, you’ll be able to offer them a better experience. Your API is a reflection of the product you’re selling. If you haven’t reached product/market fit, you’d better start thinking about pivoting or rethinking your strategy. An API alone won’t be able to change what you’re product is and its quality.

Start by improving your API sign up process that you should make as simple as possible. Documentation is a big factor of a good developer experience because it’s the first thing developers look for when they want to start using an API. To let them try your API, you can follow a sandbox approach where it’s easy to deploy and reset a full blown API testing environment. In case something goes wrong, there should be available troubleshooting tools and possibly an API status board. Always remember about communicating any changes or interesting events back to the developer community to keep them in the loop.