It’s never been easier to create an API. With Web frameworks like Flask and Express and app engines like Heroku, you can get an API up and running in hours if not minutes. The downside to this is that the easier it is to build an API, the more badly designed APIs there are going to be. And of course clients are not always much better. Developers don’t read docs properly and make their own silly errors. Heitor Tashiro Sergent from Runscope, a provider of testing and monitoring tools, goes over the top 6 errors from API providers and clients that they see every day.
The top error by far is confusing http with https. Many APIs only support one and will give you an error if you use the wrong one. Even where they support both, confusion can be the cause of errors where requests to HTTP endpoints are redirected to HTTPS ones. For example, the Express framework will not follow a 300 redirect request from an API by default. You have to specifically configure it to follow them.
The second most common error is unexpected or unhelpful error codes. This is a big time waster for provider and client. The provider wastes time on pointless support tickets and the client pulls his hair out for no good reason. Heitor himself experienced this frustration just recently. He requested an API access token and got a failed request response. He wasted time figuring out that he should have added a 64-bit encoded string with his client id and secret. The API could have just told him! A good model for error codes is Twilio that returns not only the status code (i.e. 400, 500) but a description of the error and a link to where you can find out more.
Another common error is using the wrong HTTP method. API docs are not always clear on which method to use and methods differ between APIs. Stripe API for example uses POST methods for both adding and updating entities where Runscope’s API uses PUT for updates. Both are fine. Just be sure to tell your clients which you’re using. And be consistent.
Fourth in line is invalid authorization credentials. It’s easy to get the authorization header wrong. You can write ‘authentication’ for example instead of authorization. Or you can construct the header wrongly. For OAuth2 (used by PayPal among others), you have to include the word bearer in the auth string. It’s easy to forget or write it wrongly.
Another major error is forgetting to include a content-type or accept string in your request header. Some APIs return errors if you forget since they expect you to tell them what format you’re using or what content you expect back.
A related client error is accepting an invalid content type in response. If you don’t specify an accept string, you may get HTML back that your client code can’t handle. Returning HTML happens for example by default in PHP Symfony in cases of 500 errors. It can also happen where you’re using a load balancer or routing mesh for your API. An nginx instance in front of your client code for example may return HTML in cases where it experiences a request timeout.