API & FreeMarker Issue Tracker

Issue: #2
Type: INCONSISTENCY
Area: REST API v2
Collection: all
Platform Version: <= 19.x
Summary: API v2 error responses should contain an empty items array/sequence.
Ping: DougS

ISSUE SUMMARY: It would be much easier and result in less code bloat and code repetition if API v2 error responses would contain an items property like the successful responses, the value could simply be an empty sequence/array.

The meta-structure of a successful API v2 response looks like this:

{
  "status" : "success",
  "message" : "",
  "http_code" : 200,
  "data" : {
    "type" : "messages",
    "list_item_type" : "message",
    "size" : 1,
    "items" : [
      { ... },
      { ... }
    ]
  },
  "metadata" : { }
}

while an error response looks like this:

{
  "status" : "error",
  "message" : "Invalid query syntax",
  "data" : {
    "type" : "error_data",
    "code" : 604,
    "developer_message" : "...",
    "more_info" : ""
  },
  "metadata" : { }
}

it is easy to see that there are several inconsistencies in the response structure that MUST then be handled with FreeMarker or JS when dealing with the response which leads to unnecessary checks/error handling (not because of the actual error, but because of the structure of the response object!) and subsequently code-bloat which could be simply avoided by having a consistent (even if meaningless) response structure, e.g. the properties of a successful response should always be present, also if there is an error, like:

{
  "status" : "error",
  "message" : "Invalid query syntax",
  // because this is the http code the browser actually gets,
  // but it's missing on error responses!
  "http_code" : 200,
  "data" : {
    "type" : "error_data",
    "code" : 604,
    "developer_message" : "...",
    "more_info" : "",
    "size": 0, // just give us a 0 result size
    "items": [] // just give us an empty sequence, no results
  },
  "metadata" : { } // out of interest, is this ever used?
}

This seems to be a rather easy to implement suggestion because it just ADDS properties to the error response, so hopefully not many backward-compatibility issues should arise.