REST API response describing request and returned data

Viewed 1434

Before implementation I'm considering the structure of JSON response that produces REST API I'm working on. I went through many Q/A here on SO, read many articles, recommendations and pseudo standards.

Requirements

  1. Inform client about some useful meta information - HTTP status code etc.
  2. Paging and filtering information - offset, limit and filtering queries (API client is aware of all parameters that influenced the result).
  3. Information about data collection - total records count in collection and number of returned items. API client is then able create pagination.
  4. Links to previous and next pages (just considering, not sure if this is useable for API clients but many REST APIs links section use - e.g. PayPal)

Response

This is my first draft of structure of returning search results data:

{
    "meta": {
        "status_code": 200,
        "success": true,
        "server_time": "2017-06-29T15:24:40+0200"
    },
    "request": {
        "offset": 5,
        "limit": 5,
        "query": [
            "foo",
            "bar"
        ]
    },
    "response": {
        "count": 5,
        "total_count": 754,
        "data": [
            {
                "id": "88b60cc6-70bc-4b1a-8f26-c919355d47d3",
                "name": "Name of entity 1"
            },
            {
                "id": "2f4ccda5-11bc-4ef7-b663-30c506f5118c",
                "name": "Name of entity 2"
            },
            {
                "id": "1333f2fe-a958-474e-9a82-8b343fda3aff",
                "name": "Name of entity 3"
            },
            {
                "id": "f5187143-f3b8-412b-a416-1e3a5830baee",
                "name": "Name of entity 4"
            },
            {
                "id": "2dd17750-bbdf-460a-abec-1f74e1170726",
                "name": "Name of entity 5"
            }
        ]
    },
    "links": {
        "previous": {
            "href": "http:\/\/api.example.com\/envelopes?offset=0&limit=5",
            "rel": "previous",
            "method": "GET"
        },
        "self": {
            "href": "http:\/\/api.example.com\/envelopes?offset=5&limit=5",
            "rel": "self",
            "method": "GET"
        },
        "next": {
            "href": "http:\/\/api.example.com\/envelopes?offset=10&limit=5",
            "rel": "next",
            "method": "GET"
        }
    }
}

I would like to avoid an "opinion question" to discuss the most appropriate JSON structure. I saw many opinions about envelopes in response, some services / standards it recommends, some not.

Questions:

  1. Is it good idea to return the result in this structure?
  2. Do you see some problems with this structure? What to do better?
  3. Do you see some missing values that are needed for API client? Some unnecessary values?
  4. Is needed return URL to self?
1 Answers
Related