[API] Major change coming for JSON

A change to the JSON results will be coming soon.  This is a pretty large change, so it will be coordinated carefully.

Currently, JSON results always come back as a top-level array of JSON objects.  

[  { item: { ... } },  { item: { ... } },  { item: { ... } }]

If there are no result, it is an empty array [].  This is the original design of our system and it has served us well.  However, there are new requirements that mean that we would need to provide more information back in each result.

We are going to change the returned format for JSON to be a dictionary.  The data that would have been returned in the previous format would be in an entry named as the plural form of the collection you are querying. 

{  items: [    { item: { ... } },    { item: { ... } },    { item: { ... } }  ]}

If there are no results returned, the items will be an empty array.  If there are no results due to an error condition, the result will be null.

This provides the following benefits:

• This format allows one to more easily navigate the data in Firebug
• We can provide warning or error messages ("you are using a field that is not indexed")
• We can provide deprecation messages ("this field is going to be removed")

The dictionary will always include a "returned" and "limit" entries.  Between the values in the request and these values, you can tell if your results were trimmed by the result.

{
  items: [    { item: { ... } },    { item: { ... } },    { item: { ... } }  ],
  returned: 25,
  limit: 25,
  error: "if this were an actual error, you would know"}
This data will be available to you (the developer) to help you understand why the data might be different from what you are expecting.

This change will impact the information provided in the xml and yaml formats as well, but those do not change the format in an incompatible fashion.  This information is added as attributes on the top level object.

Deployment

In order to facilitate this (and future) changes, we'll be deploying this with a new format tag, "json-x" (for eXperimental).  By changing your queries to use the -x form, you will get the new results.  Without it, you'll get the old form.  We'll run with both for a period of time and then cut over (promote -x to the main) when things have been validated.

 

This change feels like a good one.

I do wonder though, if I attempt to select on a field that is not indexed, will I get an error, a result wiht a warning, or will I bring the server to its knees if I do something too painful?

 

Since we are changing the format contained with JSON - potentially breaking your parsing of this data - we are going to be making the change to the top-level structure as well.  json-x will be promoted to the json format.

-dan

 

This change is now live as the default format for json requests.  "json-x" still exists, but it is currently the same as "json".

-dan