Application Programming Interface (API) software allows you to connect computers and programs easily. As such, it’s become so valuable that Google and Amazon generate a significant portion of their revenue.
Moreover, APIs have adopted new features that make them increasingly useful, like adhering to developer-friendly standards (e.g., HTTP) and having a software development lifecycle (SDLC) for its design, version and build.
But have you ever used an API that showed an HTML error page (instead of the JSON) that blew up your code? What about getting a 200 OK status code with a cryptic error message?
Creating an API is straightforward, but making one that’s secure and sturdy takes precision. After all, developers are only human, and there is plenty of room for mistakes that, ultimately, affect user experience.
This article will explore the six common API mistakes you should avoid to cut down the learning curve, avoid thousands of debugging hours, and get the promised results.
Mistake 1: Typing HTTP Instead of HTTPS
One of the most common API mistakes is using HTTP instead of HTTPS. Although both are protocols for transferring data, only HTTPS is secure, using Transport Layer Security (TLS) or Secure Socket Layer (SSL), which encrypts your data to prevent third-party interference.
If you don’t have an SSL certificate, anyone can access or tamper with the data you send and receive—including passwords, credit card numbers, and other sensitive information. Worse yet, they could impersonate you to access privileged data or take over your account entirely.
Beyond that, some APIs only support HTTPS while others may support HTTP for selected endpoints. Even if an API supports both, you might see some errors (e.g., the API might redirect HTTP traffic to their HTTPS counterpart, but not all are configured to follow a 302 status code).
To avoid this API mistake:
- Install an SSL/TLS certificate on your server which you can get from Let’s Encrypt or Cloudflare.
- Redirect all HTTP traffic to HTTPS by setting up 301 redirects in your server configuration file.
- Enforce HTTPS in your code by using a library or framework that can detect unencrypted traffic and redirect it accordingly. For example, the Flask web application framework for Python has an environment variable called FLASK_ENV that you can set to “development” or “production.” When set to “production,” Flask will only allow HTTPS requests.
Note that APIs may also wholly stop supporting HTTP, so you must stay updated with the changes. You can use particular tools to follow specific APIs and get notified of any changes.
Mistake 2: Having Unexpected Error Codes
Nobody likes a vague API error message that makes it confusing to resolve. Therefore, your API should be designed for the worst-case scenario which means that you need to account for all possible errors, including those caused by:
- The user (e.g., trying to access a resource they don’t have permission to)
- The client (e.g., an outdated version of your API)
- The server (e.g., a database error)
To do this, you need to use the right status codes and provide helpful error messages. For example, the 404 Not Found status code lets the user know that the page they’re looking for doesn’t exist, and the 403 Forbidden error message indicates that the user doesn’t have permission to access that resource.
If you don’t use the proper status code, you could end up with confusing error messages or, even worse, no error message at all. This can lead to wasted time spent trying to figure out what went wrong.
To avoid this API mistake:
- Use the right status codes for your error responses. The most common ones are 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), and500 (Internal Server Error).
- Include a helpful error message with each response that describes the problem and explains how to fix it. For example, “The requested resource does not exist” or “You do not have permission to access this resource.”
Your error message doesn’t have to be fancy, but it has to be clear enough for the person to understand. Having an excellent error message is the difference between a developer speaking highly of your API and them posting angry reviews on social media for the world to see.
Mistake 3: Applying the Wrong HTTP Method
You’d be surprised how many people commit the mistake of using the wrong HTTP method. Often, it’s because of poor documentation where the endpoints don’t say what methods are supported or there’s a wrong verb.
However, each HTTP method is designed for a specific purpose:
- GET: Used to retrieve data from a server
- POST: Used to send data to a server (usually for creating or updating a resource)
- PUT: Used to update data on a server
- DELETE: Used to delete data on a server
Automated tools may trick you if you’re not careful. For example, let’s say you want to create a GET request without a request-body. If you make a curl request during the -d option without the `-XGET` flag, it’ll default to POST and include the `Content-Type: application/x-www-form-urlencoded` header. This situation can lead to lost or corrupted data and wasted time spent trying to figure out what went wrong.
Daniel Stenberg also shares another possibility you might experience when dealing with redirects: “If you also tell curl to follow HTTP redirects (using -L or –location), the -X option will also be used on the redirected-to requests which may not at all be what the server asks for and the user expected.”
To avoid this API mistake, be consistent throughout your API and ensure that you have correct and updated docs. If you’re unsure of which HTTP method to use, consult the documentation for the API you’re using so your users never run into these types of errors.
Mistake 4: Sending Invalid Authorization
Use the right credentials if you’re using an API that requires authorization. These usually come in the form of an API key or OAuth token, and they need to be included in each request you make to the API.
If you don’t have the right credentials, you won’t be able to access the API—resulting in wasted time and energy trying to identify the mistakes. Worse yet, if you use someone else’s credentials by accident, you could end up with unexpected charges on your bill or even get banned from the API altogether.
To avoid this API mistake, ensure that you have the right credentials for the API you’re using. These usually come in the form of an API key or OAuth token. If you’re not sure which credentials to use, consult the documentation for the API you’re using.
For APIs that implement OAuth 2 (e.g., Paypal), you’re required to include an `Authorization` header for every request. Don’t make the mistake of typing `Authentication` which is completely different, ensure that you prepend it with “Bearer” for it to work (“Authorization: Bearer your_api_token”), and pay attention to the syntax of the header value (“Authorization: Basic base64_encode(username:password)”).
Mistake 5: Forgetting to Specify Content-Type or Accept Header
When making a request to an API, you need to specify the Content-Type of the data you’re sending (i.e., the type of data it is, such as JSON or XML) and the Accept header (i.e., the type of data you want to receive back from the API). If there are no headers, the API won’t know how to handle your request.
Of course, some APIs will accept requests without headers and default to a common format. But other APIs are strict, where they’ll return a 403 error if you’re not explicit with the Accept header value. They’ll require that you include headers on requests so the server knows what information is being sent and what format they expect to receive.
To avoid this API mistake:
- Include a Content-Type header in each request you make to an API. Doing so will tell the API what type of data you’re sending.
- Include an Accept header in each request you make to an API. Doing so will tell the API what type of data you want to receive back.
Remember that you may get confused if you test your API with various tools. For instance, some testing tools might automatically include an `Accept` header for any MIME type: `*/*` with each request, but some won’t add a default Accept header, so you’ll see different results from the same endpoint.
Mistake 6: APIs Returning Invalid Content Type for an Error
When an API request results in an error, the API should return an error response with the proper status code and a helpful error message. However, some APIs return an invalid Content-Type for their error responses—usually HTML instead of JSON or XML. This can lead to wasted time and cause problems if you’re using a tool or library that expects JSON or XML data and can’t parse HTML correctly.
To avoid this API mistake, see the following tips:
- Use the right Content-Type for your error responses. The most common ones are application/json and application/xml. Consult the documentation for the API you’re using if you have no idea which Content-Type to use.
- Remember to send an `Accept` header with your request so your API knows what response format you’re expecting. Some frameworks and web servers default to HTML, but if you’re creating an API that doesn’t return HTML, check the default error response.
- Check the routing mesh or load balancer in front of your API. If you have a nginx instance fronting your API, for example, and it encounters a request timeout (or any other error), it may return an HTML error before your API instances get a chance to know what’s happening.
Avoiding API Mistakes for Ideal Outcomes
API mistakes can lead to wasted time and frustration. However, by avoiding these six common mistakes, you can make the most of your API interactions and get the results you want. Furthermore, you can use this as a guide when looking for an API to purchase. After all, when it comes to APIs, a little prevention can go a long way.