Most of the time, when you start coding against an API, either with or without an API client, you end up producing enough errors that your error-checking is fairly robust. However, sometimes most or even everything “just works.” Which produces a conundrum:
You now have no idea how robust your error handling is (or is not).
As an example, that – ahem – may or may not have just inspired this blog post:
Say you are polling something to check for an update, every 60 seconds or so. If it fails, you want to know that and decide whether or not you should keep polling the endpoint. Everything works great. Until you get a 500 which you haven’t handled correctly (or there was a bug in your logging call or… something, ahem). Now you have an exception in your own code which breaks out of your loop independently of your API error handling. So your polling has stopped and you’ve cutoff your own ability to see what went wrong on the other end.
What I propose, is that we as API providers should include error test endpoints. Something like:
/tests/errors/500
/tests/errors/503
etc
(note: 404 is obviously easy)
In theory RESTful APIs would all return errors in the same way with HTTP error codes and the like, but the practical reality is that this just isn’t the case. Some even return 200s with JSON strings that include errors. Even if they we’re all perfect, you still might want to wrap them in behaviors (like sending an email notification) depending on the message contents, which really leaves you in a predicament if the errors are hard to intentionally produce. You can even make a compelling argument that API client development should start with these endpoints.
I’ve opened an Issue to add these endpoints for YourTrove’s API and I will follow this up with a blog post on the Trove blog when those endpoints are deployed.
– better.