[Developers] minor change in search api behavior (empty result setwill no longer be an error)

[brendan]

I'll just add, there's something interesting in this seemingly minor  
change: the subject of how to handle errors in freebase service  
requests, particularly the role of the http status code and the  
freebase service code (the json "code" key).  I welcome any  
corrections by the freebase architects here but I think it boils down  
to:

2xx and a  "code":"/api/status/ok" is a pretty reliable thumbs up. In  
our empty search example, you will probably need to handle the empty  
case (e.g. "Nothing found, sorry") but the point of the original  
thread here is: it's not an error.


5xx returned (with no json) at all means something horrible has gone  
wrong with the service (definitely Metaweb's bad, let us know!)
4xx series, we try to follow the spec, and in some cases it indicates  
something wrong in your code e.g.
     404, "Not Found" (no json) you've hit the wrong url
     400, "Bad Request" (probably with a json response) you've got a  
bad url parameter in your request, or your json is mal-formed. inspect  
the "code" and "messages"
2xx is a good request/response but you now have to inspect the "code"  
to make sure it's "/api/status/ok"

2xx by itself does *not* necessarily mean everything's fine. You may  
need to look at the "code".

A couple of  completely different examples where 2xx *doesn't* mean  
everything's fine:

- mql syntax error: Valid json, just not anything mql recognizes as  
valid, e.g:

{
   "status": "200 OK",
   "code": "/api/status/error",
   "messages": [
     {
       "info": {
         "expected_type": "/type/object",
         "property": "foo"
       },
       "query": {
         "foo": null,
         "error_inside": "."
       },
       "message": "Type /type/object does not have property foo",
       "code": "/api/status/error/mql/type",
       "path": ""
     }
   ]
}

- Database timeout. Here it gets somewhat nuanced. You've made a hard  
database request (give me all 4 million topics in one page please).   
If it takes longer than 8 seconds it will timeout and you will get  
something like:

{
   "status": "200 OK",
   "albums": {
     "code": "/api/status/error",
     "messages": [
       {
         "info": {
           "host": "graph04.p01.sfo1.metaweb.com",
           "detail": [
             "timed out"
           ],
           "timeout": 8.0,
           "port": 8100
         },
         "message": "Query timeout",
         "code": "/api/status/error/mql/timeout"
       }
     ]
   },
   "code": "/api/status/ok"
}

Now, this is tricky, because you don't really have a way of knowing  
what to pass on to the user: "Stop asking such hard questions!" or  
"freebase.com might be slow right now"  But the logic here is: your  
request was valid and I've got a valid response for you, in effect,  
"that's too hard for me right now".   For most applications, you've  
tuned your queries and know they should be fast so you may very well  
want to interpret this as a service failure (and let us know!)

Brendan

On Jul 17, 2008, at 9:39 AM, brendan wrote:

> credit goes to David Flanagan who is putting together our 2nd gen.  
> mql and services docs which, I trust, are going to be awesome. His  
> "JavaScript" book rests just to the left of my keyboard as I type  
> this, thus my high expectations ;)
>
> Brendan
>
> On Jul 16, 2008, at 6:33 PM, Arthur van Hoff wrote:
>> Great idea.
>>
>> From: developers-bounces at freebase.com [mailto:developers-bounces at freebase.com 
>> ] On Behalf Of brendan
>> Sent: Wednesday, July 16, 2008 6:30 PM
>> To: For discussions about MQL\, Freebase API and apps built on  
>> Freebase
>> Subject: [Developers] minor change in search api behavior (empty  
>> result setwill no longer be an error)
>>
>> Hi all,
>>
>> This change is no likely to affect any apps/scripts out there, but  
>> here goes:
>>
>> Currently, if you make a search request and the service finds  
>> nothing, it comes back as an error.  e.g.:
>>
>> http://freebase.com/api/service/search?prefix=insx&type=/music/artist&type_strict=all
>>
>> {
>> "status": "200 OK",
>> "code": "/api/status/error",
>> "messages": [
>>  {
>>    "message": "No search results found",
>>    "code": "/api/status/error/search/empty"
>>  }
>> ],
>> "result": []
>> }
>>
>> In the coming weeks this will change.  The expected response for an  
>> empty result will be:
>>
>> {
>>   "status": "200 OK",
>>   "code": "/api/status/ok",
>>   "messages": [
>>     {
>>       "message": "No search results found"
>>     }
>>   ],
>>   "result": []
>> }
>>
>> This response just seems more sensible, particularly given that the  
>> service allows the user to request a very constrained result  
>> (strict=all means results must match the given type parameter value)
>>
>> If your code has error handling for this "no results" case, you  
>> might want to make sure this change won't break things.
>>
>> Let me know if you have any questions/concerns.
>>
>> Brendan
>> _______________________________________________
>> Developers mailing list
>> Developers at freebase.com
>> http://lists.freebase.com/mailman/listinfo/developers
>
> _______________________________________________
> Developers mailing list
> Developers at freebase.com
> http://lists.freebase.com/mailman/listinfo/developers

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freebase.com/pipermail/developers/attachments/20080717/1d97f5de/attachment-0001.htm