This blog post is a guest contribution from Jonas Borjesson, Tech Lead SIP at Twilio Inc.
Harnessing the power of APIs is the key to competing in the new era of software. APIs provide the agility developers and businesses need to iterate and innovate quickly, and they’re everywhere. Businesses all over the world are looking to roll out or even acquire APIs, but if they don’t succeed at winning over developers, those services are not likely to last.
Businesses release APIs for two primary reasons:
- They want to expose their services through an API
- They release an API that supports an existing product or API
When we talk about APIs, generally we’re speaking of the first category, otherwise known as “REST” APIs, where REST stands for Representational State Transfer. These are the chief means by which developers access services from any provider, and the most important thing to remember is that the developer is the customer.
Developers are the lifeblood of innovation, and developer adoption and retention are crucial to the survival of any API. Developers can be independent, employed in large enterprises, or building projects in their spare time, but the common thread among them is that they want easy-to-implement, accessible technology to fuel what they want to build.
You need to consider three fundamentals for building an API for the developer—your customer.
Respect the developer
Empowering developers to experiment, innovate, and deploy applications built on your API starts with respecting their time and effort. For example, don’t punish your developers with maintenance windows. Your business can have operating hours, your API cannot. However, respecting the developer really begins with the documentation.
Write the docs first. Developers want easy-to-navigate, easy-to-read documentation that helps them get up and running instantly. Copy-and-pasteable quickstarts are crucial to achieve this, and your documentation should feature a variety of quickstarts that are easy to build, including sample applications based on specific use cases.
Don’t assume you know what languages developers prefer. That’s where Helper Libraries, or software developer kits (SDKs), are critical. Do the research, and evolve your documentation as developer preferences change. Your goal is to offer Helper Libraries in as many relevant languages as possible, especially the most popular. Stack Overflow publishes an annual global developer survey. Start there.
The gratification of building an app in a few minutes will encourage developers to keep iterating and experimenting with your API, eventually building powerful applications.
Keep it simple, but powerful
At every step of designing your API, ask yourself, “Can I build a meaningful application in five to 10 minutes?” Answering this question and revisiting it often, will help you address a number of issues along the way, especially complexity.
Complexity is important, but don’t fall into the trap of equating complexity with power. You want developers to build powerful use cases on top of your API, but power shouldn’t come at the sacrifice of simplicity. Different problems require different tools, but the complexity of those tools should be opt-in.
Consider Legos. With the same blocks, you can start simple and gradually build to create more complex models. If someone wants to build a car out of Legos, they’re not required to use exactly 1,000 blocks of specific colors and sizes. The person is free to determine how complex, how powerful, and how extensive that model will be.
Another note on power: don’t overpromise on latency, which is the time it takes for your API to respond to a request. It’s one thing for a sample app with a single request to work immediately; it’s a different matter when an app is making hundreds or thousands of calls per hour.
Developers need to trust that an app in production will perform the same as it did when it was a prototype. If you overpromise, developers will start to make assumptions on latency that will most certainly cause problems as they scale upward. Consistency is what’s important. If your API performs the way you claim it performs, developers will trust it to build powerful applications—simple or complex—at global scale.
Iterate early and get feedback
No one gets the perfect API on day one, and that’s okay. Getting feedback early and often from developers will increase the likelihood of you producing an API that is useful to them.
In the early stages of designing your API, write documentation for sample applications for a few important use cases that you intend your API to solve. Put the first version of the API and the documentation in front of developers and get feedback on how it would feel building those applications. Make sure you and your API team do the same.
With your API still in alpha, this initial feedback is extremely important for informing any massive changes you may need to make. Once the API reaches beta, keep in mind that the apps developers are building on top it are also in beta. Forcing them to make major changes at this point is a great way to disrespect the time and effort they’ve put into working with your technology.
Even a simple change in behavior will break whatever they’re building. For example, if you decide in beta to no longer accept a subset of characters in a string where previously you accepted any character, any app that uses those characters will break. You need to understand even these smallest details of a developer’s journey in working with your API, and the best way to do that is through participation in regular hackathons.
Internally, your teams will surface potential bugs and incompatibilities while devising new uses for your API. Externally, you can get instant feedback from the developers who will use your API every day. Far more than just pizza and beer, hackathons provide valuable insight into what it’s like for your customers—developers—to work with your technology.
The Future of Your API Belongs to the Builders
Developers want to be able to solve problems with the power of software, and you want them to include your API in their toolbelt. But remember, experimentation is the prerequisite to innovation. Make building and iterating as easy as possible for developers, and they will adopt your new technology. They’re the gatekeepers to the future of your platform. Following the best practices I’ve described will keep your API healthy while empowering your customers to build the next generation of applications.
This blog post first appeared on ProgrammableWeb.
