Bruno Pedro

5 steps to API frustration

2017-10-19

5 min read

This article is a satire that describes what often happens to developers that are looking for an API and want to integrate with it. I’m pretty sure that some of the things have happened to you at some point in time. If you’re an API provider, you should think hard about how you’re dealing with the five topics that I’m about to expose.

1. Search #

It all starts with search. You want to find an API that can offer you a particular feature. You also want to be able to integrate your software with it quickly. You don’t have time to implement things yourself, and that’s the main reason why you’re looking for an API that does the job for you. Most of the times you look around, but you can’t find anything that suits your needs.

Then you reach out and ask for advice. You receive suggestions from your peers. People that have problems similar to yours will tell you their stories and how they solved their problem with a certain API. You ask yourself “Why not?” and you think about giving it a try. After all, the worst that can happen is you not liking it and getting back to doing your search. Right?

After hearing great things about the API that you decided to give a try, you actually want to test it. Testing it means you want to make a few calls using your favorite API client. You also want to be able to understand if the API responses make sense and what code needs to be written to consume it. So you land on the Web site of a company you’ve never heard of before and, to be able to give their API a try, they ask you to sign up.

You feel a bit upset about having to sign up, but you do it anyway because you really want to use this API. Remember how much time you spent searching it and all the good recommendations you received from trusted people? So you sign up only to discover that you actually have to share your credit card details and start a trial of the “Pro” plan just to be able to test the API. The signup process finally ends, and you manage to get an API key so you can run some integration tests. You start digging for information on how to consume the API.

3. Documentation #

You finally find out where the API documentation is and you start regretting the moment you entered your credit card details. The only information that’s available is a verbose list of all the possible operations including all the parameters and responses. You look for examples and quick start guides, but you find none. You look for SDKs, but you find none. Not even one created by the community.

After some more searching, you end up on a third-party community Web site where developers like yourself share their experiences integrating with the API. You finally find some examples shared by other people and decide to follow a specific one that is close to what you want to implement. After a couple of hours of failures, you understand that the example had been written against a previous version of the API. You finally decide to write an SDK yourself.

4. Implementation #

After having spent about a week writing an SDK that implements the full API reference you decide to open source it. You then share the SDK with the API community and get in touch with the company behind the API, so they know about it. They publish a link to your SDK on their API documentation page which makes you feel that, at least, you’re making other people’s lives easier.

You become popular in the API community Web site, and you start receiving pull requests on your SDK. The SDK gets more and more visibility because it’s getting linked from different places. You get to a point where you’re spending more time maintaining the SDK than actually doing your job which is integrating with the API. You definitely need to find help.

5. Integration #

Inside your company, people get excited with the SDK, and you manage to assemble a small group of developers to help you with the implementation of an integration. A product owner starts documenting how the integration will work and how end users will benefit from it. Developers document the whole process and follow all the best practices. Things are looking good.

Suddenly during a demo to the board, the integration that you’ve been building for the past few months stops working. You first think it’s something temporary and give it another go, but it seems to have stopped working. During the post-mortem analysis, your team discovers that all the unit tests are green and everything is working as expected. After some hours of debugging you find out that a new version of the API has been released which is not backward compatible.

Summary #

At this point you have two choices: going back to searching for another API or re-implementing the SDK so that it works with the API latest version. You feel frustrated because you’ve invested so much in this project and you’ve persuaded so many people to join you. What shall you do?