Response structure inconsistency

issue.md

In front-end side, our implementation when fetching a data from the server is that the response data structure should be consistent.

e.g when the response has data and in the form of an object structure

{
  "total": 22,
  "per_page": "1000",
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 22,
  "data": [
    {
      "id": "4",
      "jo_no": "JO-0000004",
      "jo_name": "Northwestern Mutual",
      "scheduledHours": [
        {
          "date": "2016-07-04",
          "hours": 0
        }
      ]
    }
  ]
}

e.g when the response has no data, we expect the structure should be like this

{
  "total": 0,
  "per_page": "0",
  "current_page": 0,
  "last_page": 0,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 0,
  "to": 0,
  "data": []
}

or as simple as this one

{
  "data": []
}

in above example the idea is that no matter what is the response, the data structure should be in object.

Another scenario that we encounter is that their are some api's that will response in array structure.

[
    {
         "id" : 1,
         "name": "hello-world
    }
]

when the above example happens, our little friend will come and hunt us.

In our end, in order to fix the issue we will try to add an config to our code to tell the app that we expect the response is in array structure.

After adding the config we will now expect that the response should always be in array structure.

e.g when the response has data

 [
    {
      "id": "4",
      "jo_no": "JO-0000004",
      "jo_name": "Northwestern Mutual",
      "scheduledHours": [
        {
          "date": "2016-07-04",
          "hours": 0
        }
      ]
    }
  ]

e.g when the response has no data

  []

Another scenario that we encounter and possibly we can't fix it in our side is when the response has data it will return an object structure and if the response has no data it will return an array structure. The is where the response structure inconsistency issue comes in.

e.g when the response has data and in the form of an object structure

{
  "total": 22,
  "per_page": "1000",
  "current_page": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null,
  "from": 1,
  "to": 22,
  "data": [
    {
      "id": "4",
      "jo_no": "JO-0000004",
      "jo_name": "Northwestern Mutual",
      "scheduledHours": [
        {
          "date": "2016-07-04",
          "hours": 0
        }
      ]
    }
  ]
}

e.g when the response has no data and in the form of array

  []

IMHO, we should REALLY discus this issue so that we can prevent our little badcfg friend to come again and hunt us in near future.

I suggest that we will use the first example data in the form of an object structure or we can use some JSON response standards. Standard JSON API response format?

Feel free to add your thoughts guys.!