Let’s Improve Error Messages
How API providers should save our time.
TL;DR
Properly implemented API error reporting speeds up the development and prevents potential bugs.
True Story — Time Wasted
Several months ago, we were integrating a 3rd party API to Amio.io. It was a regular connector. We picked a provider, followed their docs and started programming. We created tests too and released to production.
After several days, a client pointed out an incorrect behavior that started to occur randomly. After spending hours trying to hunt the bug down we asked the provider for a support. He told us that we should use sender_id instead of senderid.
We copy pasted the bad value from their documentation. And yeah, errors happen, nothing wrong with it. The wrong part was that their server let us send them the wrong value and didn’t report any errors what-so-ever! The time we lost on that simple typo was almost 2 days.
Time Savings
It may be just my opinion but I believe that speed in SW development has gained a significant importance lately. Teams are breaking down their monoliths to micro services, lots of new apps are shipped using continuos-delivery or even continuous-deployment and developers may pick their SaaS providers based on the quality of their documentation, demos, etc.
One thing that is usually not taken into account is how useful the error reporting is. This part of API can give a nice boost to your dev. Why? Because if you spot errors quickly, the correction is cheap (quick too).
A Responsible SaaS
I don’t believe that it’s integrator`s responsibility to always go and verify if the error reporting is actually useful. We, providers, should consider it automatic to give our users a useful error-reporting. As a minimum, it should tell when a request is wrong and that some parts of the request are not needed. Yes, it goes against the well-known Robustness Principle but it’s like if you take the developer and lead him down the shortest and safest path to his final implementation.
Do you want to make integration of your API even more pleasant? Guide the integrator right from the error returned. Don’t make her consult the docs every time she enters a wrong value. Offer her allowed values, show the limits and pinpoint which part of the request was wrong.
Some Examples Please!
Some of our requests maybe quite long with deeply nested structures and arrays, e.g. horizontal scroll messages (no need to read the code, just notice the complexity ;-)
{
"channel": {
"id": "{{facebook_messenger.channel.id}}"
},
"contact": {
"id": "{{facebook_messenger.contact.id}}"
},
"content": {
"type": "structure",
"payload": [
{
"title": "Leaf salad with smoked eggplant.",
"text": "9.5 €",
"image_url": "https://wikimedia.org/Fish-lunch.jpg",
"item_url": "https://example.com/daily-menu",
"buttons": [
{
"type": "postback",
"title": "Buy it",
"payload": "buy"
},
{
"type": "postback",
"title": "Sell it",
"payload": "sell"
},
{
"type": "link",
"title": "Show Details",
"payload": "https://example.com/food-1"
}
]
},
{
"title": "Beef burger with Coleslaw salad",
"text": "12.0 €",
"image_url": "https://wikimedia.org/burger.JPG",
"item_url": "https://example.com/daily-menu",
"buttons": [
{
"type": "url",
"title": "Show Details",
"payload": "https://example.com/food-2"
}
]
}
]
}
}
In the code above, a programmer used link instead of url. We will tell him where he made the mistake and how to fix it:
{
"message": "Property 'type' with value 'link' does not match any allowed value: url, phone, postback.",
"field": "content.payload[0].buttons[2].type",
"rejected_value": "link"
}
Farewell
In case you integrated Amio, I hope that you appreciate how our error reporting saves your dev-time. If you are one of our API providers, I hope that you’ll improve your error reporting. :-P
Have a nice weekend!
