V2 API Change Summary (08/17/2016)

A detailed summary of changes being made to the V2 API

The following is a detailed summary of changes being made to the V2 API:

Starting on 08/17/2016 we will be changing our V2 API to conform with the JSON-API specification. In particular, this will introduce breaking changes – with backwards compatibility until October 1st, 2016 – to the following live endpoints:

  • GET /v2/expiring_token
  • GET /v2/medias/#{id}
Note
The only publicly documented endpoint for the V2 API is the expiring_token endpoint. The medias endpoint is not yet documented for public use, and should only be used privately by the Wistia Uploader at this time.

What will be changing?

The format of the JSON for both success and error responses will be changed to conform to JSON-API.

Moving to JSON-API will change our success responses and error responses differently for both of these endpoints. The request URI and parameters will not be changing for any endpoint.

Success Responses

Success responses in the V2 API currently return raw JSON resources. For example, in the old response format an expiring token might be returned as:

{
  "id": "expiring_token_e4281538058e6d79a7938fc8bd654d283b99d6744afea3c7029e551294a1913a",
  "type": "access_token",
  "token": "expiring_token_e4281538058e6d79a7938fc8bd654d283b99d6744afea3c7029e551294a1913a",
  "scopes": ["all:all"],
  "required_params": {},
  "expires_at": 1471623113
}

JSON-API requires that we nest our primary response data in the data field. The data field can contain any of the following: a single resource object, an array of resource objects, a single resource identifier object, an array of resource identifier objects, null, an empty array. In short, we can return one or many objects or references to those objects (by specifying the required type and id fields which together uniquely identifier a resource).

In our cases, both of our existing endpoints (/v2/medias/#{id} and /v2/expiring_token) will be modified to return a single resource object. This means that we’ll be nesting primary data in the data field. Also, that data field will contain an object with id, type, and attributes fields.

Here’s an example of what the /v2/expiring_token endpoint will return in the new response format (and /v2/medias/#{id} will be changed similarly):

{
  "data": {
    "id": "expiring_token_e4281538058e6d79a7938fc8bd654d283b99d6744afea3c7029e551294a1913a",
    "type": "expiring_access_token",
    "attributes": {
      "type": "access_token",
      "token": "expiring_token_e4281538058e6d79a7938fc8bd654d283b99d6744afea3c7029e551294a1913a",
      "scopes": ["all:all"],
      "required_params": {},
      "expires_at": 1471623113
    }
  }
}

Error Responses

The JSON response body format of our errors will also be changing. None of the HTTP statuses or codes of our errors will be changing. Similar to how JSON-API specifies a format for data, it also specifies a format for errors. The errors field of the response body returns an array of error objects. The spec also gives several suggestions for field names and definitions, and we have chosen to adopt several of them.

Our errors have all been standardized to follow the same format and conventions. In particular, we’re adopting the code and detail fields; code will identify the type of error and detail will give further information about what went wrong. Note that all other error fields have been removed. We are not supporting backwards compatibility for previous fields.

In addition, meaningful HTTP statuses have been retained for all errors.

Below is an example of what an error response body looks like:

{
  "errors": [
    {
      "code": "service_unavailable",
      "detail": "Wistia is in read-only mode. Please try again later"
    }
  ]
}

Need Support?

If you have any questions or concerns about these changes, please contact us at support@wistia.com. We’re here to help!