The top level representation returned by any resource request should always be the resource itself. For example, the call

GET /v1/products/76124

should return a response similar to

{
    "status":"OK",
    "recordCount":1,
    "startTimestamp":"2013-12-02T19:31:35.5362308Z",
    "endTimestamp":"2013-12-02T19:31:35.6299946Z",
    "timeTaken":0.0937638,
    "data":[{
         "products" :[{
               "product_id": "76124",
               "name": "The Amazing Widget",
               "weight": "7.2 oz",
               ...
          }]
    }]
}

In this example, the response data is embedded within an envelope containing other related data specific to the request, including any status codes, timestamps, etc. This information is not required and may be eliminated in favor of simply returning the “data” hash at the top level.

Note that the “products” value – which should contain the information specific to the Product resource, as indicated in the endpoint – is actually a one-item array containing a hash rather than a hash itself. This allows the API to use the same structure whether it’s returning a single requested object or whether returning a list of objects. Returning a consistent format like this makes it easier for the client developer to create a single handler for the response. For example,

GET /v1/products

should return a list of products in the same format:

{
    "status":"OK",
    "recordCount":3,
    "startTimestamp":"2013-12-02T19:31:35.5362308Z",
    "endTimestamp":"2013-12-02T19:31:35.6299946Z",
    "timeTaken":0.0937638,
    "data":[{
         "products" :[
		 	{
               "product_id": "76124",
               "name": "The Amazing Widget",
               "weight": "7.2 oz",
               ...
          	},
		 	{
               "product_id": "84567",
               "name": "Rubber Ducky",
               "weight": "4.6 oz",
               ...
          	},
		 	{
               "product_id": "76124",
               "name": "Whoopie Cushion",
               "weight": "2.2 oz",
               ...
          	},
			
		 ]
    }]
}

This same response format should be returned whether the resource is called directly, i.e.

GET /v1/products/76124

Or whether it’s called through a relationship, i.e.

GET /v1/categories/39/products/76124