Testing for an empty JSON document
I have a RESTful service that performs a search and returns the results as JSON, and if there’s no results I return an empty document, {}.
Now I don’t know what the original author’s situation is or how much control they have over the API they’re consuming, but I can definitely project my own experiences on his blog post. At the link above he provides is a good example of the right solution to the wrong problem. It handles the response given, but the response itself is the real problem.
When you are using a RESTful web service to search and it cannot find anything, you shouldn’t wind up in this situation to start with. The fix isn’t better client code, the fix is a better web service.
When your service does a search without finding anything, it should return 404 Not Found. I’ve had to deal with too many web services that only had 2 response codes: 500 if there was an uncaught exception or 200 OK for everything else. There is a sea of other HTTP response codes and limiting yourself to just those two limits the usefulness of your service.
If Angular gets a 404 response it won’t invoke the .success() block, it will go straight to .error() handler. (.success() and .error() have their own issues but that’s another blog post) That would have prevented this situation in the first place. In my project at work we are doing just this: a search that doesn’t find anything returns a 404. When people have looked at our network traffic they have complained to us about these errors, but by sticking to HTTP semantics we’ve avoided this all together.
“But it shouldn’t return an error code if the service executes without errors!” – The 400 series of status codes is for client errors, requests that can’t be fulfilled. If I request a URL that doesn’t have a file on a static website, I get a 404. Why should it be different if I request an ID that doesn’t exist in your database? Why should a search for something that doesn’t exist and may never have been OK?
“But I don’t want errors in my code!” – When you add RESTful web services to your architecture, you are making HTTP part of your execution flow. A 404 response is kind of like an exception: you don’t want to hide it from your client any more than you would want to catch all exceptions. Let the client decide what to do when nothing is found, don’t try to pretend everything is OK.
So please, if you’re exposing a web service over HTTP use Status Codes correctly. Or don’t, it gives me something to blog about.
As the author of the original article, thanks for the tips here about the best practice of returning a 404 from a RESTful service if no data is found… I was unaware this is what you should do, and since the service is my own, I can definitely update it. Thanks for the advice!
I wouldn’t go so far as to say that this is a best practice, some smart people disagree with me on the subject. But I’m still pro-404 since it allows you to provide a specific HTTP response code, and it fits with what I would want user agents to do (don’t cache, don’t index, allow you to find out if there are results just from a HEAD request).
One thing to keep in mind if you follow my advice is your probably still want to send a JSON body with more information, just like you would send HTML with a 404 response to a browser. Oh, and if you’re returning a list of search results an array might be a better data container than an object.