Software Engineering
Developer Experience Principle 2: Easy to Use
Freshness Warning
This blog post is over 4 years old. It's possible that the information you read below isn't current and the links no longer work.
28 Sep 2020
The second principle of a great developer experience is that the product surrounding your API is Easy to Use. It’s important that a developer finds it easy to code against your API, but this principle covers everything else. How a developer works with everything else that comes along with the product. From getting started to managing access to debugging to payment, this principle covers everything the developer needs to do to use your product.
The key to this principle is self-service. The more the developer can do themselves, the better you’re exemplifying this ideal.
Start with where the developer starts: gaining access. When a developer has discovered your API and wants to try it, how do they get started? How do they sign up for an account or get an API key or whatever your system requires for access control? The less friction you put into the signup system, the easier developers will have it.
It’s easy to tell when the API isn’t a focus of the product. Gaining access means asking someone to set you up. A developer that wants to get started needs to ask someone at your company to create an account, provide an API key, or otherwise turn on access. You can’t risk losing the attention of the developer once you have it. Even if there’s not a competing API the developer could choose, there are competing priorities for their attention. Adding friction that slows them down could mean they move on to working on something else.
I once worked with an API where getting an API key required an email to support. They’d generate a key for you and send it over. I was at a weekend hackathon in Portugal, and the US-based support team was on Monday through Friday hours. My API key stopped working for some reason and I needed a new one. I happened to have the CTO’s mobile phone number, and a text message to him sorted me out in short order. But unless you’re going to hand out your CTO’s contact information to every developer in the world, you’ll want some self-serve setup options.
For paid APIs, make sure a developer can start without complex payment terms. If possible, create a free trial or a free usage tier so a developer can explore without payment. In many companies, it’s surprisingly hard for a developer to set up payment from their company. Large enterprises often don’t allow someone to expense software or services purchases. Smaller companies can have unclear policies on getting reimbursed for buying products. You don’t want a developer to get excited by your API only to be blocked because they’re uncertain if they’ll get reimbursed for a $50.
For products that need a contract or other formal relationship between the developer’s company and yours, consider offering credit card payment for low-level usage, even if such usage isn’t financially interesting to you. One company I worked with charged $12,000 per month for access to their API. That was their entry-level pricing plan. Payment was via wire transfer only. But to attract developers, they had a limited-use plan that was $30 on a credit card.
If your product requires a large amount of customer data to be useful, offer a sample data set. Developers may want to try your API before they have a lot of data in the system. Or they may not have access to their actual company’s data. Many of Github’s APIs are for customer’s code repositories. But developers can use those same API calls to access any public open-source code repo. This gives the developer a sample data set they can code against.
Consider that developers who work for your customer might not have access to their company’s production data or account. Cisco Webex offers a wide range of admin APIs that allow the automation of user administration, organization-wide configuration, and security tasks. Cisco recognized that most developers at their customers wouldn’t have access to this sensitive data in the customer’s account. Webex provides an administrative sandbox, a dummy customer account that any developer can access.
Making it Easy to Use means providing self-service for as much as you can. Most API products are incomplete without a developer portal that allows developers to manage their accounts, see their usage, manage payment, get API keys, and view documentation. Easy to Use means getting out of the developer’s way and making sure that a motivated developer has everything they need to build on your API.
Top image licensed CC-BY from Timothy Vollmer on Flickr