REST API response describing request and returned data

Question

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?

Answer 1

Opinion questions are hard, but I'll try.

First of all, your question should not be addressed to community, but to client itself. Nothing clears assumptions about missing/necessary values better than such feedback.

The structure itself is good enough, at least as a draft. When designing responses you need to remember that you are basically locking yourself up, since clients don't like fundamental changes in API. Only lot of incremental "please add just one more field here". You are doing good job in thinking far enough, about meta fields, pagination and separating actual response, but don't think you can predict everything. You won't. Maybe look for something like HAL or JSON Collection. At least as an inspiration.

In the end design of API is evolutionary and mostly client driven process. So talk to your client.