Few things are more frustrating than finding that a request made to your API has failed. The biggest issue in this scenario is that troubleshooting it can be tricky, especially if the information about the failure is either minimal or presented in an obscure way.
If API errors are causing you stress, here are a few steps you can take to figure out what is going on and prevent further problems from arising.
Embrace standardization
Often it’s the arcane nature of error reporting with regards to API requests that creates such a conundrum when failures arise.
If the formatting is API-specific, or altered according to some other forgotten set of principles based on aspects like the endpoint in question, then it’s easy to get bogged down in time-consuming ameliorative tasks immediately.
The simplest solution is to make your life easier with the use of a standardized approach to formatting error responses. This means that the API client will pump out reports in a uniform, unified way while doing away with the fragmentation of the past.
The Internet Engineering Task Force has proposed just such a standard format, and it promises to deliver benefits both for API developers as well as those organizations that use them.
Implement consistent formatting
So what exactly does this standard involve? Well, for both JSON and XML there are a number of human-readable components which go together to give you an insight into the root of the error.
First, there’s the type URI, pointing you in the direction of a more detailed explanation of the error type that has been identified.
Next, there’s the title, which essentially summarizes the error to give you an at-a-glance idea of what’s going wrong.
Then, there’s the detail, which is an extended explanation of the title which specifies the exact nature of the issue at hand.
Finally, there’s the instance, which is another URI that can either point to a page with additional info on the error in question, or simply be used as an identifier for the failure.
You don’t need to use all of these each time, but the ‘type’ component is effectively compulsory. In XML, this would look a little like this, in an example where a transaction fails due to a lack of credit:
<?xml version=”1.0″ encoding=”UTF-8″?>
<problem xmlns=”urn:ietf:rfc:7807″>
<type>https://example.com/probs/out-of-credit</type>
<title>You do not have enough credit.</title>
<detail>Your current balance is 30, but that costs 50.</detail>
<instance>/account/12345/transactions/abc</instance>
</problem>
Consider the framework being used
More good news is that this standard has been adopted across a number of API frameworks, with tools that enable its implementation without the usual rigmarole.
From RESTful APIs and Node.js to Ruby on Rails, a critical mass of support is building, and it’s sensible to throw your hat into the ring with your own API efforts.
The more use it gets, the more it will benefit those who build, maintain or simply consume APIs. And layering it on top of any existing error reporting you are doing should not be too much of a stretch.
Final thoughts
Finding out where the failure is when an API request doesn’t work correctly has to be a process which starts with the reporting, otherwise you stand little chance of pinpointing the problem with no evidence to guide you.
Even if you are just a consumer of APIs, you can make a difference by getting in touch with API builders and asking them to alter their error handling so that it accommodates the aforementioned standard. This is a mutually beneficial move, and one which more people are making every day.
