4 ms·
Not handling error semantics well: sometimes things fail, and thinking through what happens when they do fail is one of the more complex problems in programming
by saurik 14y ago
Not handling error semantics well: sometimes things fail, and thinking through what happens when they do fail is one of the more complex problems in programming. I can easily just write more code to handle authentication or interoperability (I'm a programmer: I write code; I have no fear of writing a lot of code), I have never found APIs with "poor documentation" to be a serious issue, and the terms of service on APIs are usually fine.
The real problem is that when the API fails I get back what... one of a massive set of possible error conditions with opaque code numbers and some random english string that I guess I have to render all the way out to the user in the hope that they understand it or that it is even relevant to them? Are new error states going to be added in the future? Who even caused the error, so I know who to give it to: was it me, was it the user, or was it a natural disaster?
What happens if the response from your server to mine is lost after you've already committed the change; is there an idempotent way I can verify what happened? Is it ever the case that I can get back a success and the request didn't actually work after the fact? If so, how do I figure out what requests failed, and am I stuck occasionally making, quite literally, a few million requests to check the status of every transaction I've ever previously executed?
If you are making callbacks to my server (ugh, this always sucks, and should be avoided except as a notification to cause an early poll: you can design systems that are both efficient in requests and don't require push) are you retrying failures? What do you even consider to be a failure? Again, is there an idempotent way that I can determine whether I've already seen the callback when retried? When retries happen, what happens to the ordering between messages?
Most web APIs these days seem to believe "oh, I'll make some really pretty documentation for a single call that shouldn't be able to fail anyway, and yeah... webhooks!", and the result is a horrible mishmash of garbage that, when it fails, simply "fails" in a way that pretty much requires a human to go interact with the state of the entire system and figure out what may have been forgotten or lost, or worse: how to fix the result.
- tadfisher 14y ago> What happens if the response from your server to mine is lost after you've already committed the change; is there an idempotent way I can verify what happened? What is the "right way" to handle this? Say I'm building a REST API, and a user POSTs to a collection, which returns the URL to the posted resource in the Location header. POST in this case isn't idempotent, so what mechanism can I provide for the user to check that this resource was indeed created? A search method?
- saurik 14y agoI am not certain I know the "right way" to deal with this, but a common way that makes my life as a consumer of APIs much easier is to make the API idempotent (if I pass the same request, including a nonce, I get back the exact same result as the earlier request). There are other solutions, though; I will claim that most of them that I have seen, however, involve making the client much more complex (such as a search system, unless the search system allows me to search by the nonce; an example of doing the search solution reasonably is Amazon Payments, and an example of doing the idempotent API reasonably is PayPal v74.0+). (BTW: the possibly short snippet for my long post might me "API semantics that make it impossible to build a completely automated solution even in the case of failures, either transient or persistent".)