JSON data wrapping

lighthouseknowledge

While working with a development team on a RESTful solution I start proposing wrapping the service response/output in another object. This would allow us to write some META data about the response.

This META data would help developers with understanding what was going on with their request and the response provided by the service. A kinda talk back method to AJAX or REST responses.

A lot of people would say why would you need this? Well maybe you have a service that is open to the public like Twitter. You want developers to be able to access your service and understand your data without them calling or emailing you all the time. Maybe your information is labelled or structured differently than theirs. The META data provided in the wrapper would allow them to determine how to interpret the information to suit their needs.

Wrapper structure sample: 


{
  "statusCode" : 1000,
  "requestID" : "63D62A09-AA1F-88CF-E890EDBF000F4F8E",
  "data" = {
    "message" : "Success", 
    "totalRows" : 1, 
    "columns" : {}, 
	"results" : []
  },
  "eventName" : "",
  "requestParams" : {}
}

Elements/Attributes of the wrapper

Path Notes
statusCode This status code is used to denote what is going on with the service or method being accessed.It is different from that of the Header status or AJAX request status.

These values can be set to reflect your status indicators.
requestID The requestID is optional and has many possible uses.First, it can be used to let developers know that the response is not cached.

Second, if you are keeping a log of requests for security, debugging, or user statistics this value will come in handy. Developers could submit a bug with the JSON packet that they received. This could help you debug possible issues with the data they supplied the service.
data This is where we would store data that the developer might want to display to end-users.
data.message The message field allows the service to send text or human messages back to end-user or developer. This message can be related to the numeric status indicator or independent.For example, say that the developer was making a request to log in. The statusCode could be 5000 letting the developer know that the method is working correctly. But, the was an error. The message element would hold the server response Password is not correct.

These messages can be handing in notifying the user of bad/missing parameters or with debugging of where the service broke.

data.totalRows This is an optional element. It is here to help the developer display the number of records being returned.
data.colmuns This is a optional element. I sometimes use it to display the column names of the query and denote if the column is a string, integer, boolean, array, UUID, GUID, or date.This helps the developer know you are returning 1 or 0 for a boolean response. And not for a number count.
data.results This is where you would normally store all the data that would be displayed to the end user.
eventName This element is used to help the developer verify that the are accessing the right method.

I normally user the path to the service. /com/members/readMembers/
requestParams This array would list all of the parameters that were sent as part of the request. This helps the developer debug responses.

Full structure sample


{
  "statusCode" : 1000,
  "requestID" : "63D62A09-AA1F-88CF-E890EDBF000F4F8E",
  "data" = {
    "message" : "Success", 
    "totalRows" : 3, 
    "columns" : {
      "productID" : "UUID", 
      "title" : "string", 
      "price" : "integer", 
      "availableUnits" : "integer"
    }, 
    "results" : [
      {
        "productID" : "502AD47D-05C6-4A47-9DD11458B8211EEB", 
        "title" : "Dell Inspiron 15 15.6\" Laptop Computer - Black", 
        "price" : 229.99, 
        "availableUnits" : 24
      },
      {
        "productID" : "93E84FE4-5367-4DD3-87F15C6A862ADA11", 
        "title" : "AOC e2252Swdn 22\" LED Monitor", 
        "price" : 99.99, 
        "availableUnits" : 102
      },
      {
        "productID" : "605C7476-7673-4C62-9E506D4331E03AAE", 
        "title" : "Apple iPad mini 16GB Wi-Fi Space Gray", 
        "price" : 259.99,
        "availableUnits" : 0
      },
    ]
  },
  "eventName" : "/com/products/resaleProducts/",
  "requestParams" : {
    "isSaleItem" : 1
  }
}