Standardise middleware API responses

[diego-G]

Parent #899

The current Middleware does not implement an standardized API response. It needs to create a better Middleware according to the REST API standards. I suggest to follow http://jsonapi.org . This standard includes for example the possibility to introduce HATEOAS: referencing to another endpoints directly in the response (self link, related entity links, pagination links, etc). It offers to the user an smoothly navigation.

Also, setting this standard will allow us to have several developers working in parallel on same issues, overall the ones related to the API refactoring #457 #225 .

The proposed structure is as follows:

Success

HTTP/1.1 200 OK
Content-Type: application/json
{
  "meta": {
    "total-pages": 13
  },
  "data": [
    {
      "type": "articles",
      "id": "3",
      "attributes": {
        "title": "JSON API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "created": "2015-05-22T14:56:29.000Z",
        "updated": "2015-05-22T14:56:28.000Z"
      }
    }
  ],
  "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
  }
}

Error

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/first-name" },
      "title":  "Invalid Attribute",
      "detail": "First name must contain at least three characters."
    }
  ]
}