<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">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: <div><br></div><div>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.</div><div><br><div><br></div><div>5xx returned (with no json) at all means something horrible has gone wrong with the service (definitely Metaweb's bad, let us know!)</div><div>4xx series, we try to follow <a href="http://www.w3.org/Protocols/HTTP/HTRESP.html">the spec</a>, and in some cases it indicates something wrong in your code e.g.</div><div> 404, "Not Found" (no json) you've hit the wrong url</div><div> 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"</div><div><div><html>2xx is a good request/response but you now have to inspect the "code" to make sure it's "/api/status/ok"</html><html><br></html><html>2xx by itself does *not* necessarily mean everything's fine. You may need to look at the "code".</html><html><br></html><html>A couple of completely different examples where 2xx *doesn't* mean everything's fine:</html><html><br></html><html>- mql syntax error: Valid json, just not anything mql recognizes as valid, e.g:</html><html><html><br></html><html>{</html><html> "status": "200 OK", </html><html> "code": "/api/status/error", </html><html> "messages": [</html><html> {</html><html> "info": {</html><html> "expected_type": "/type/object", </html><html> "property": "foo"</html><html> }, </html><html> "query": {</html><html> "foo": null, </html><html> "error_inside": "."</html><html> }, </html><html> "message": "Type /type/object does not have property foo", </html><html> "code": "/api/status/error/mql/type", </html><html> "path": ""</html><html> }</html><html> ]</html><html>}</html></html><html><br></html><html>- 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:</html><html><br></html><html><html>{</html><html> "status": "200 OK", </html><html> "albums": {</html><html> "code": "/api/status/error", </html><html> "messages": [</html><html> {</html><html> "info": {</html><html> "host": "graph04.p01.sfo1.metaweb.com", </html><html> "detail": [</html><html> "timed out"</html><html> ], </html><html> "timeout": 8.0, </html><html> "port": 8100</html><html> }, </html><html> "message": "Query timeout", </html><html> "code": "/api/status/error/mql/timeout"</html><html> }</html><html> ]</html><html> }, </html><html> "code": "/api/status/ok"</html><html>}</html><html><br></html><html>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!)</html><html><br></html><html>Brendan</html></html><html><br></html><html>On Jul 17, 2008, at 9:39 AM, brendan wrote:</html><br class="Apple-interchange-newline"><blockquote type="cite"><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">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 ;) <div><br></div><div>Brendan</div><div><br><div>On Jul 16, 2008, at 6:33 PM, Arthur van Hoff wrote:<br class="Apple-interchange-newline"><blockquote type="cite"><span class="Apple-style-span" style="border-collapse: separate; color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: 0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0; "><div lang="EN-US" link="blue" vlink="purple" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div class="Section1"><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-size: 10pt; font-family: 'Comic Sans MS'; color: rgb(31, 73, 125); ">Great idea.<o:p></o:p></span></div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-size: 10pt; font-family: 'Comic Sans MS'; color: rgb(31, 73, 125); "><o:p> </o:p></span></div><div style="border-top-style: none; border-right-style: none; border-bottom-style: none; border-width: initial; border-color: initial; border-left-style: solid; border-left-color: blue; border-left-width: 1.5pt; padding-top: 0in; padding-right: 0in; padding-bottom: 0in; padding-left: 4pt; "><div><div style="border-right-style: none; border-bottom-style: none; border-left-style: none; border-width: initial; border-color: initial; border-top-style: solid; border-top-color: rgb(181, 196, 223); border-top-width: 1pt; padding-top: 3pt; padding-right: 0in; padding-bottom: 0in; padding-left: 0in; "><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><b><span style="font-size: 10pt; font-family: Tahoma, sans-serif; ">From:</span></b><span style="font-size: 10pt; font-family: Tahoma, sans-serif; "><span class="Apple-converted-space"> </span><a href="mailto:developers-bounces@freebase.com">developers-bounces@freebase.com</a> [<a href="mailto:developers-bounces@freebase.com" style="color: blue; text-decoration: underline; ">mailto:developers-bounces@freebase.com</a>]<span class="Apple-converted-space"> </span><b>On Behalf Of<span class="Apple-converted-space"> </span></b>brendan<br><b>Sent:</b><span class="Apple-converted-space"> </span>Wednesday, July 16, 2008 6:30 PM<br><b>To:</b><span class="Apple-converted-space"> </span>For discussions about MQL\, Freebase API and apps built on Freebase<br><b>Subject:</b><span class="Apple-converted-space"> </span>[Developers] minor change in search api behavior (empty result setwill no longer be an error)<o:p></o:p></span></div></div></div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; ">Hi all,<o:p></o:p></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; ">This change is no likely to affect any apps/scripts out there, but here goes:<o:p></o:p></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; ">Currently, if you make a search request and the service finds nothing, it comes back as an error. e.g.:<o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><a href="http://freebase.com/api/service/search?prefix=insx&type=/music/artist&type_strict=all" style="color: blue; text-decoration: underline; ">http://freebase.com/api/service/search?prefix=insx&type=/music/artist&type_strict=all</a> <o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><br>{<br>"status": "200 OK",<br>"code": "/api/status/error",<br>"messages": [<br> {<br> "message": "No search results found",<br> "code": "/api/status/error/search/empty"<br> }<br>],<br>"result": []<br>}<o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; ">In the coming weeks this will change. The expected response for an empty result will be:<o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span class="apple-style-span"><span style="font-family: Arial, sans-serif; ">{ </span></span><span style="font-family: Arial, sans-serif; "><br><span class="apple-style-span"> "status": "200 OK", </span><br><span class="apple-style-span"> "code": "/api/status/ok", </span><br><span class="apple-style-span"> "messages": [ </span><br><span class="apple-style-span"> { </span><br><span class="apple-style-span"> "message": "No search results found" </span><br><span class="apple-style-span"> } </span><br><span class="apple-style-span"> ], </span><br><span class="apple-style-span"> "result": [] </span><br><span class="apple-style-span">}</span></span><o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-family: Arial, sans-serif; ">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)</span><o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-family: Arial, sans-serif; ">If your code has error handling for this "no results" case, you might want to make sure this change won't break things.</span><o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-family: Arial, sans-serif; ">Let me know if you have any questions/concerns.</span><o:p></o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><o:p> </o:p></div></div><div><div style="margin-top: 0in; margin-right: 0in; margin-left: 0in; margin-bottom: 0.0001pt; font-size: 12pt; font-family: 'Times New Roman', serif; "><span style="font-family: Arial, sans-serif; ">Brendan</span><o:p></o:p></div></div></div></div></div>_______________________________________________<br>Developers mailing list<br><a href="mailto:Developers@freebase.com" style="color: blue; text-decoration: underline; ">Developers@freebase.com</a><br><a href="http://lists.freebase.com/mailman/listinfo/developers" style="color: blue; text-decoration: underline; ">http://lists.freebase.com/mailman/listinfo/developers</a><br></div></span></blockquote></div><br></div></div>_______________________________________________<br>Developers mailing list<br><a href="mailto:Developers@freebase.com">Developers@freebase.com</a><br>http://lists.freebase.com/mailman/listinfo/developers<br></blockquote></div><br></div></div></body></html>