Introduction

Please read this page carefully!

Encoding Requests and Decoding Responses

Request bodies must be encoded as JWE tokens, and encrypted using your assigned API key. Bodies of successful responses will be likewise encoded and encrypted, again using your assigned API key. Error responses from the API won't be encoded.

The API will reject a request if the token doesn't conform to certain specifications. Your application must be able to encode and decode JWE tokens using the following header requirements:

  • alg: Must be PBES2-HS512+A256KW
  • enc: Must be A256CBC-HS512
  • p2c: At least 1000
  • p2s: Length at least 8

API Versioning

The API is versioned with URL prefixes: /v1/api/example, /v2/api/example, etc. When we launch a new version of the API, we won't immediately take down the previous version. We'll keep it around so you have time to upgrade to the newest version. We won't keep more than two versions up and running, though. When version 3 is released, version 1 will be deprecated and taken offline shortly thereafter; version 2 will be kept online until version 4 is released; and so on.

A new version of the API will only be released for breaking changes. The following are considered breaking changes:

  • Removing an endpoint
  • Removing a property from a response model
  • Adding a required property to a request model
  • Adding required URL query string parameters
  • Changing the type of a response model
  • Changing the type of a property on a response model

Compliant client software must ignore properties it does not know about.

The following types of changes are not considered breaking changes:

  • Adding a new endpoint
  • Adding a new optional property to a request model
  • Adding a new property to a response model
  • Adding new optional query string parameters

These lists aren't exhaustive, but illustrate the idea that if a change can be supported in an existing version such that an out of date client need not notice the change, then a new version is not required.