Guidance

Our responsibilities

These are the responsibilities we take on as the host of our APIs. We commit to:

  • Not make breaking changes without giving due notice (examples below)

  • Give at least 60 days notice of any upcoming breaking change, the end of which will include a period of at least 30 days where the old and new request structure will both work. In the rare event that we cannot keep to these timescales we will get in touch with you directly

  • Use standard HTTP response codes

  • Ensure that our APIs conform to the documentation that has been shared with you

Your responsibilities

These are the behaviours we expect you to stick to as the consumer of our APIs:

  • Give us least 60 days notice of any upcoming breaking change, the end of which will include a period of at least 30 days where the old and new request structure will both work. In the rare event that you cannot keep to these timescales please let us know

  • Use standard HTTP response codes

  • Ensure that your APIs conform to the documentation that has been shared with you

  • Allow non-breaking changes (examples below)

  • Tell us as soon as possible if you’re having a problem with one of our APIs, this includes problems such as:

    • Being unable to connect to our API

    • Being unable to process responses from our API

    • Getting errors from our API

  • Honour standard HTTP response codes (e.g. following redirects)

  • Get in touch with our support/dev team before making any significant change to your usage pattern (e.g. you intend increase the amount of data you are sending us by an order of magnitude)

Recommendations

We recommend that you:

  • Re-use access tokens; they’re valid for 12 hours

  • Retry failed requests if you want them to be actioned

    • e.g. network errors, HTTP 429, HTTP 5xx

  • Implement monitoring on your integration with our APIs

Examples of breaking changes

  • Addition of a new required parameter

  • Removal of an existing endpoint

  • Removal of any field in the response (either required or optional)

  • Removal of a query parameter

  • Restructuring of the input or output format, for example:

    • Making a top-level field a sub-field

    • Changing the location of errors to be in-line

  • Changing the name or data type of an existing input parameter or output value

  • Changing the name of a field

  • Changing the resource name

  • Changing a response code

  • Changing error types

  • Changes to existing permission requirements

Examples of non-breaking changes

  • Addition of a new endpoint

  • Addition of a new optional parameter on an endpoint

  • Addition of a new field in a response

  • Reordering of fields in a response

  • Changing text in error messages

PreviousPrinciplesNextEasy Connect

Last updated