Written by Marjukka Niinioja on
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.
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.
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.
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.
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 Open API documentation also for mocking (= simulating) the API before any or all the code has been written and to create tests.
Picture 1 shows one an example from IBM Cloud API Connect developer portal. It uses Swagger UI internally and lets the user download the Open API 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.
Picture 2 shows a request used for sending SMS messages via APIFONICA API using Postman. See the arrow pointing to the “Code” feature. Clicking it shows you a screen with code example. Use the select list in the top of the form to switch languages. For some reason this feature was something I found only by accident, it is a little bit hidden.
Picture 3 shows the APIFONICA API documentation page, where a cURL example code snippet is copied. cURL is quite easily understandable and most developers know it. It’s not really a programming language but a command line scripting language and tool. It’s quite easy to use also in various programming languages or at least read and adapt.
There are of course many other issues that can have impact on your developer experience and API adoption. Like how your API actually works and how misleading your initial instructions are.
Interested to know how you can improve your API discovery and developer journey? There are many more things you can do, starting from thinking about your page and API search engine optimization. We have a pretty standard review process in place for 10 most common areas. Prizing is based on the number of endpoints your API has, so this will fit you even if your API is small.
Contact us and let’s talk!