More metadata about requests, errors, and warnings coming to your responses

We want to tell you even more about your API requests. On November 1st we'll begin including a response_metadata field in HTTP API responses.

At first it will include a warnings array, just as the top-level JSON response does today. API warnings are great example of the kind of information we want to communicate in this response metadata, so please forgive our duplication.

Later we'll include a messages array. It will include human-readable descriptions of errors or warnings generated by your request.

What's changing?

Today when you get a response that contains a warning, the response looks something like this:

{
    "ok": true,
    "warnings": [
        "missing_charset"
    ]
}

When this change ships, that same response would look something like this:

{
    "ok": true,
    "warnings": [
        "missing_charset"
    ],
    "response_metadata": {
        "warnings": [
            "missing_charset"
        ],
    }
}

And then someday, we'll send wordy messages prepended with [WARN] and [ERROR], like:

{
    "ok": true,
    "warnings": [
        "missing_charset"
    ],
    "response_metadata": {
        "warnings": [
            "missing_charset"
        ],
        "messages": [
            "[WARN] A Content-Type HTTP header was presented but did not declare a charset, such as a 'utf-8'"
        ]
    }
}

The above example message text is hypothetical and the actual text used in these messages will always be subject to change. We promise no knock knock jokes.

How do I prepare?

Most developers need do nothing to prepare. You may want to verify that your code or libraries you use won't explode when encountering new fields and embedded data structures. Generally this is a non-issue for everyone.

If you interpret the warnings we send today, you may want to relocate your consideration to the new warnings field descending from response_metadata.

When is this happening?

We'd like to introduce this low risk change on November 1st, 2016.

Feel free to contact us with your feedback here.