API Guarantees

The Ravelin API mostly receives and returns data using JSON encoding.


In HTTP responses, the Ravelin API will include the Content-Type header to indicate how the body should be interpreted. For example, with a JSON API endpoint, we will include the header Content-Type: application/json.

Compatibility guarantees

Ravelin may occasionally add new fields to API responses. As part of our backwards-compatibility guarantee, any new field will not change the meaning of any old fields.

Given that we may add new fields, you must ensure that your decoders do not error in the presence of unrecognised fields. To check this, we add random, novel fields (unknownField:...) to our responses in the sandbox (test) environment.

Ravelin may introduce a new version of an endpoint. If this happens, this will be clearly communicated in advance of its introduction. We will endeavour to make it easy to migrate to any new endpoint.