What Are Six of the Most Common API Mistakes?

These days, with the number of tools available, building an API can happen in a matter of minutes. But there is a big difference between whipping up an API, and crafting one that is secure, reliable and meets the user’s expectations. Heitor Tashiro Sergent from Runscope, lays out six of the most common mistakes that arise from APIs that weren’t made with enough care.

The first mistake is using HTTP Instead of HTTPS. One case where this is problematic is when an API redirects HTTP traffic to its HTTPS equivalent but the web Framework you are using is not configured to follow a 302 URL redirect status code. In addition, all APIs should be using HTTPS even if you don’t think you’re transmitting sensitive data. Privacy and security should be a default and by using HTTPS, you avoid relying on the Web Service to make a subjective call.

Mistake number two has to do with poor error messages that leaves developers in the dark as to what the true problem is. The recommendation is to make good use of HTTP status codes and include clear error messages. Sergent points to Twilio as being a leader in this respect.

The use of the wrong method, be it GET, PUT, or POST is another common mistake. This can easily happen if the API developer relies on past assumptions and uses the wrong method. This also happens frequently due to poor or out of date Documentation. Sergent recommends providers to be consistent with how methods are used throughout the entire API and to make sure the documentation is correct so as to not confuse end users.

Sending invalid authorization credentials is another common mistake. Sometimes this is as simple as confusing Authentication for authorization headers in APIs requiring OAuth 2. Syntax issues can also be a frequent cause of failed requests.

Number five on the list of common mistakes is not specifying either the accept header or content-type header. Some APIs don’t require these headers in their requests, simply defaulting to a format like JSON, while other APIs are more strict and will cause the request to fail if the header is missing. Since these headers specify the format of the information that will be sent or received between client and server, it is important that these are included.

The final mistake has to do with APIs returning invalid content types when there is an error. For an API consumer this can happen if a request is sent without an Accept header leaving the API unsure what response format you're expecting. If you are an provider and your API shouldn’t return HTML, you should be sure to check the defaults error response.

These mistakes are simply the most common but by no means an exhaustive list. To help catch a lot of them ahead of deployment, you’ll want to implement some sort of testing process into your development cycle. Be sure to read our series on Why and How to Test and Monitor Your APIs (and the Tools to Use) for more information.

Be sure to read the next API Design article: How to Use GenStage and WebSockets to Optimize Consumption of Rate-Limited APIs

Original Article

6 Common API Mistakes