Just like beehives, APIs connect all the parts of your 'hive' to streamline your business. Great APIs are the key to becoming a main player in the “new era” of software. APIs provide the agility developers need to innovate. Companies worldwide are looking to develop APIs, but if they fail at winning over developers, their services are not likely to last. In this blog, we consult with API experts on how to best create APIs that developers will actually want to use.
According to Jonas Borjesson, Tech Lead SIP at Twilio Inc., “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.”
Writing documentation first gives developers an easy-to-navigate doc that can help them get the API running faster. Copy-and-paste starts are crucial to this, and the documentation should feature an variety of them that are easy to build, including sample applications based of specific use cases.
Use software developer kits to research what language a developer may prefer, rather than assuming what they’d like. According to Borjesson, your main goal is to offer Helper Libraries in as many relevant developer languages as possible—particularly the most popular languages. If they are able to build an app within a few minutes, developers will feel gratified and be encouraged to keep using and experimenting with your API to build more powerful applications.
Worried about making mistakes with your API? Read our blog on the most common API mistakes you might be overlooking and learn how to avoid them, right here.
As you design your API, you should be asking yourself questions throughout the process such as “Can I build a meaningful application in five to 10 minutes?” By revisiting this question frequently throughout the design of your API, you can easily address issues and complexity as the API is built.
“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,” Borjesson said in his MuleSoft blog.
Don’t over promise on latency — the time it takes for your API to respond to a request — either. Developers need to trust that an app in production will perform the same as it did while it was being tested. If you over promise, developers will make assumptions about latency that will cause problems as they scale upward. Consistency is key; if your API performs the way you claim it will, developers will trust it and be more likely to use it to build powerful applications.
No matter how good your team is, no API is going to be perfect from the moment its launched. That’s okay! What’s important is to get feedback early – and often – so that you can improve the API and make it into something developers will want to continue to use.
Borjesson says, “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.”
The feedback you get from the alpha stage of your API is critical. Once the API reaches beta, keep in mind that the apps developers build on top of it are also in beta. Forcing developers to make major changes at this point will make them feel disrespected, since you’re undermining the work they’ve done using your technology. Even a simple change in behavior can break what they’re building, so understanding a developer’s journey is crucial. One way to do this is by participating in “hackathons” to learn more about how development works.
While your internal teams will bring potential bugs and issues to life while devising new uses for your API, getting instant feedback from developers can be even more valuable. Hackathons provide valuable insight into what it’s like for developers to work with your API in the day-to-day.