How to get more API users?

I recently helped a company who wanted to improve their developer experience. Their quarterly goal was to gain even more adoption and new customers to their API in their native US market.

They are currently in the middle of doing all the changes my thick report suggested, so I’m not mentioning the name. But let’s say they are one of the very best in their field and cater to the biggest customers, like LinkedIn.

Their API developer journey and that of their competitors had many issues, most of them very typical. For the benefit of all product managers and developers out there, I wanted to share a few of the tips. Let’s make the world a better place for us API consumers out there.

Your Site Must Not Be Pretty

One of the main things is that people need to actually find out and notice that you have an API. If you design a pretty site with nice graphics, it might still not speak to the developer’s soul. Devs want your site to look a bit rough. It’s best if it’s full of technical details. Cut down polished graphics screaming: “You need to talk to the sales first!”

As part of the review, I was comparing also their competitors’ developer journeys. We decided to ignore a few early candidates because you needed to talk to the sales to get access to the API. You might be tempted to think this was actually a good thing, your competitors should not get to your API too easily. Remember though, the forms I needed to fill and the messages I got back were downright off-putting. So as a developer, I would have run far from those anyway.

Is Your API A Hidden Gem?

You also need to stop and look at your whole website through the eyes of someone for whom your API might be a “delighter” feature. They might not be looking for it, though. They could be project managers, product managers, architects or business people. So make sure your API stands out in the main product pages and don’t hide it as the very last link of your website footer.

There are also lots of other ways to get your API discovered, but this is the no-brainer thing to fix.

‍

Make Love not War with Developers

What makes developers happy, once they have found out you have an API? My fellow author friend Jarkko Moilanen is using UI metrics to APIs: 3-30-3 rule says that

• A developer must understand in 3 seconds why are you offering the API, what problem does it solve?
• 30 seconds should be enough to try out the API, make the first request
• A developer must be able to use the API within 3 minutes from her own code

This sounds like a tough call, but I’m serious. If your developer experience and customer journey are not up to those metrics, your prospects are going to move onto the next API. Or if they are your internal developers or hired help, they will be unmotivated and bill you more. Unless your API is doing something no other API is solving or if your company is the best in their field, you might get away with a slower process. But don’t bet on it.

Some companies have solved this by offering only code examples as API documentation. They seem to think that jumping to the last step of the process is the most important one. But no, don’t take shortcuts. If your potential API consumers do not understand why they should use your API, whatever code you throw at them won’t help.

That doesn’t mean that offering code examples or SDKs wouldn’t be a good thing. It’s only useful if you have the resources to maintain them. If your Github repo says “last updated 4 years ago” your developers will read “abandoned” and move forward. There is no programming language in the world that would not need some updates every year. And your API has probably been updated anyway, so what are the chances that your SDK would work anymore.

Make sure there is a process on how to answer questions and issues coming through the SDK repository from developers. Also, consider that your own developers might not have the best bedside manner when someone is “criticizing” their baby.

Roles and Tools to the Rescue

If you are still reading this, you are probably thinking that providing an API requires you to have an army of developers and another army of user experience specialists. No, but your API does need a Product Manager. And I don’t mean a Product Owner used in Scrum, but a Product Manager, who treats the API as a product, with customers. Their job is to explain to sales, marketing, customer service and developers what problems the API is solving. How does it provide value to the customers?

Also, it’s PM’s job to see that all the documentation and the developer journey are working. PM needs to work together with a community manager. Their mutual job is to ensure issues and feature requests coming from your community get prioritized and answered.

What about the code and the SDKs, and documentation? Create your API using Open API specification. Or at least generate it from the code. Then you are already half-way in getting documentation and code examples. Make sure your Open API documentation includes request and response examples. You are then able to use API management platforms or open source tools. Tools can generate both the documentation and the code examples with various language automatically. This has a couple of other benefits, too. Your API consumers can use the Open API document in their code and automated testing. You can use the OpenAPI documentation also for mocking (= simulating) the API before any or all the code has been written and to create tests.

Picture shows one an example from IBM Cloud API Connect developer portal. It uses Swagger UI internally and lets the user download the OpenAPI document as well as copy automatically generated example code in different languages.

‍

One easy tool to remember is also Postman. You can copy code examples from any API request you are making there. Postman supports OpenAPI and native Postman collections for publishing APIs.

In this video, you can get a glimpse of what difference a good developer experience makes for API adoption. The video shows how to make simple requests to an exchange rate API using Postman.

‍

‍

‍