I’m working on a new project which uses Etsy’s API. As far as APIs go, theirs is pretty neutered. There’s no user authentication whatsoever so the only data you can get from it is what’s available to the general public. Since you can’t authenticate, you certainly can’t write any data, so things like allowing users to add Etsy items to their favorites aren’t possible.
Working with their API I found another “quirk.” If you try to getUserDetails on a username which doesn’t exist it won’t return null or false or an empty object. Instead, it responds with HTTP status code 404.
Wait, what?
This means I have no way of differentiating between an error in my URI and a simple case of a defunct username. In fact, this behavior is contrary to what Etsy’s own documentation suggests. Their sample code dies on any status besides 200, which makes sense although you’d probably want to handle the error more gracefully. Now I have to look up the status code and try to guess whether I got the 404 because of a malformed URI or because the username was wrong. That will make debugging super fun!
404 is an HTTP error. A correctly formed API query with a null result should not return a 404. Argh. In english terms, a 404 means “I don’t have the information you’re looking for.”
You could argue that Etsy simply doesn’t have the userinfo for that user, because it doesn’t exist, and therefore 404 is appropriate. But that’s a cop out. Etsy DOES know that user’s info: it’s empty. If I’m querying a database of all known users, and getting back a subset of said users based on my input, Etsy’s response should be “there aren’t any matching users” not “I don’t have that information.” A 204 error would be more appropriate.
Edit: Apparently this is becoming a common thing. Although I haven’t seen it with any other APIs I’ve worked with. And let me state for the record that just because other people do it doesn’t make me think it’s any less of a dumb idea.
Edit again: Someone who is less sleep deprived than myself pointed out that the body of the 404 responses does contain useful information, which I had missed earlier. So in this case I will concede to being wrong, although I am still not a fan of this approach because it means my script relies on the exact English wording of their error messages. Carry on.
Actually, presenting a database as a virtual HTTP tree is the post-RPC hip thing to do these days. http://en.wikipedia.org/wiki/Representational_State_Transfer
Oh gross. Put me down as officially Not A Fan.
I’m in the camp that if I submit a well formed query I should get a consistently formed response, regardless of the number of records returned. And that 404 errors shouldn’t be doing double duty.
I’m not familiar with the Etsy API, but you requested a resource (in this case a user profile) that did not exist; a 404 is a perfectly valid response.
I agree it should be well-documented though, and the lack of authentication thing is bullshit.
My problem with the approach is that I have no way of differentiating the responses between good methods and invalid data vs calling a method incorrectly.
So
http://beta-api.etsy.com/v1/users/revolvingdork (correct) returns data. good.
http://beta-api.etsy.com/v1/users/revolvingdorks (invalid user) returns 404.
But
http://beta-api.etsy.com/v1/user/revolvingdork (good user, incorrect method) also returns 404.
This makes debugging a pain. A 204 no content response would be more appropriate IMO.
The body of the responses are different. Try it.
$ curl http://beta-api.etsy.com/v1/users/revolvingdorks?api_key=blah
user name revolvingdorks does not exist
$ curl http://beta-api.etsy.com/v1/user/revolvingdork?api_key=blah
Can’t route command ‘/user/revolvingdork’.
Interesting.
In that case it looks like I’m wrong. Wouldn’t be the first time, probably not the last either.