An Application Programming Interface (API) is a software interface that serves as a medium to connect computers and computer programs. APIs have become increasingly valuable that they generate a large portion of many companies’ revenue, including companies such as Google, Amazon, and Salesforce. Today, APIs have adopted useful features that have only added to their value – for example, modern APIs adhere to developer-friendly standards (such as HTTP), and have its own software development lifecycle (SDLC) for its design, build, and version.
Creating an API can be quick and straightforward, however creating one that is secure takes more work and precision. API developers are only human and therefore mistakes can happen, which can ultimately affect the user experience. The following are a few common API errors that may occur:
1. Using http:// instead of https://
Although sometimes API supports both HTTP and HTTPS, missing a single “s” can lead the developer to errors. For example, some APIs redirect HTTP traffic to their HTTPS counterpart, but not all frameworks will be configured to follow a 302 status code. APIs may also stop supporting HTTP, and while good API providers would let users know beforehand, it’s important to stay up-to-date with any changes.
2. Outdated Caching
Caching is essential to the internet and the user experience. By saving data into a public file, users can access the same resources time and time again without overloading the server. Caching is generally a great practice, but improper implementation can be a hindrance and nuisance.
For example, say there is an eCommerce API system that is setup to cache on a frequent basis, in order to update stock and reduce server load during busy cycles. If the API is having a major sale, a larger volume of items would be added to the listing endpoint. However, what becomes problematic is how the data is presented while the listing endpoint is being cached. Customers can see new data if the data is being presented in live form via a dynamic web front, but the poorly implemented caching could lead to a clickable item, a picture, and even a description, all of which would lead to a 404 page when clicked. This is simply because the resolution for that endpoint has not been cached yet.
In this instance, it is important for the developer to test the API as if they are the consumer. This will allow them to approach the code with more caution and attention in order to enhance the user experience and minimize any caching mistakes.
3. Unexpected error codes
API error messages point developers in the right direction whenever there are inconsistencies in the code. However, sometimes unexpected error codes arise and lack sufficient information of what went wrong, leaving the developer scrambling to figure it out themselves.
It is important for API providers to streamline the development process, as exemplified by Twilio, a communications platform. Twilio implements provide links in error messages to point the developer in the right direction to troubleshoot any mistake that may have been made in the code. By maintaining concision and providing more useful information for the developer, any mistake can be quickly addressed.
4. Using the wrong HTTP method
It is very common for developers to use the wrong HTTP method. Oftentimes this can be blamed on poor documentation, but tools can also lead to obstacles if the developer is not attentive. For example, in the situation when a developer wants to create a GET request with a request-body, it is best to make a curl request using the -d option and not use the `-XGET` flag, which will automatically default to POST and include the `Content-Type: application/x-www-form-urlencoded` header.
Other times, we might fall into past assumptions and use an incorrect method. For example, the Runscope API uses POST when creating new resources such as test steps or environments, and PUT when modifying them. But Stripe’s API uses POST methods when creating and updating objects.
No matter which approach the developer chooses, it is important to be consistent throughout the API and make sure to have correct and up-to-date documents, so that the users don’t run into this error.
5. Sending invalid authorization credentials
If a request is failing, it is important for the developer to ensure they are using the correct word in their code. For example, APIs that implement OAuth 2 usually require the developer to include an `Authorization` header for each request. However it is common to confuse that with `Authentication`.
It’s also important when using HTTP Basic authentication to pay close attention to the syntax and grammar of the header value. The form is the follows:
Authorization: Basic base64_encode(username:password)
Common mistakes include forgetting the ‘Basic ‘ (note the space before the inverted comma) prefix, not encoding the username and password, or forgetting the colon between them. If an API provider only requires a username without a password (like Stripe, where the API key is the username), the colon after the username is needed, even if there’s no password.
6. Not specifying Content-Type or Accept header
Accept and Content-Type headers negotiate the type of information that will be sent or received between a client and server. Some APIs will accept requests that don’t contain any of those headers and just default to a common format.
However, other APIs might return a 403 error if you’re not explicit about the Accept header value, and will require you to include those headers on requests. This alerts the server as to what information the client is sending, and also what format should be expected to be received.
7. APIs returning invalid content type when there is an error
For API providers, some frameworks and web servers default to HTML. So if a developer is creating an API that has no business returning HTML, it is important to check the default’s error response.
Another aspect to be vigilant about is the routing mesh or load balancer that sits in front of your API. For example, if there is an nginx instance fronting your API and it encounters a request timeout or other error, it may return an HTML error before your API instances even have a chance to receive information about what is occurring.
8. Failure in team communication
In any company, failing to communicate between teams can lead to a cascade of errors and damage control. For example, if the development team does not notify the support team about a type change, the support team would then disperse faulty information and consequently harm the user experience. Likewise, if the UX team does not communicate an interface change to the development team, it could lead to a break in the website’s functionality and the API would be largely inaccessible.
The solution to this situation is simple – communication and team effort. When a plan is set up during the blueprinting stage, it is best to adhere to it and notify the appropriate teams about every revision that is made.
These are some of the most common mistakes that may occur in APIs. They can go unnoticed and lead to more time spent on troubleshooting and debugging. But with the help of the above pointers, combined with a higher level of awareness and attention to detail, these errors can be avoided.
Leave a Reply