[Developers] Changes to Freebase API.

[Tim Kientzle]

We're making some minor changes to the way we return status  
information in the Freebase HTTP API.  The primary goal is to make  
the different API requests return JSON-structured information  
consistently, so that your code can retrieve error information more  
easily.  The key changes are the addition of a new "code" field that  
provides more useful and consistent status information and some  
adjustments to the layout of the "messages" array.

Many of you are probably using the "status" field in the outer  
envelope, which carries an HTTP-like status code.  Generally, if the  
string value begins with "200", then the request succeeded, otherwise  
it failed.

But HTTP status codes don't really provide enough information to  
distinguish a range of specific errors, so we're adding a new "code"  
field that contains a path-like string.  That string will always  
begin with "/api/status/ok" or "/api/status/error".  Check for one of  
those prefixes to tell whether a request succeeded or failed.  Most  
error statuses will contain additional detail that you can use to  
determine the best way to handle this error.  For example, the /api/ 
trans services will return "/api/status/error/trans/notfound" to  
indicate that a requested object was not found.

Many of our existing APIs have a "messages" array.  Unfortunately,  
these have been formatted somewhat inconsistently, so we're going to  
adjust our current APIs to make them more consistent.  Each element  
of the "messages" array describes a single specific problem.  For a  
form submission, for example, there can be a separate message for  
each submitted field.  Generally, the first message will be the most  
important; if your UI only supports a single message, use that one.

Each element of the "messages" array is itself a dictionary with at  
least two fields:
   * "message" is a free-form English-language description of a  
problem.  This should be suitable for display to end users.
   * "code" is a status code similar to the "code" field in the outer  
envelope, though generally more specific.  For example, some problems  
will elicit a simple "/api/status/error" in the outer envelope and  
each message dictionary will contain a more precise code for a single  
problem.  We intend the code values to be useful as keys for looking  
up customized error messages.
   * Other fields may also appear, depending on context.

We'll be updating our documentation soon to reflect these changes.   
In the meantime, feel free to ask questions on  
developers at freebase.com about any aspect of our API.

These changes were deployed to sandbox.freebase.com on Monday, June  
11, and should reach www.freebase.com later today.

Tim Kientzle
Metaweb Technologies, Inc.