Deprecation Process

Overview of our approach to deprecating functionality on the GraphQL-based APIs.

  less than a minute  

Policy

From time to time we’ll want to deprecate, and ultimately remove, functionality from our GraphQL API.

Reasons for this can include, but are not limited to:

  • A field is no longer used
  • We have a better existing alternative
  • Too complex / non-adherent to our API design principles.

Don’t worry though - we follow the following process to ensure we give everyone enough time to make the necessary changes.


The Process

Identify

  • We identify the fields we wish to deprecate
  • Update the deprecated_reason for the relevant field in our GraphQL schema, which will include:
    • The final removal date (currently 6 months from identification)
    • An alternative field / approach that can be used

Notify

  • We’ll make reasonable attempts to notify the users of deprecated fields via email
  • We’ll maintain and update this page (which we recommend you check from time to time!)

Remove

Following the 6 month notification period, we ultimately remove the deprecated field, we will of course take into consideration whether there is still any significant traffic on the field prior to final removal.