Deprecation Policy

When an operation (Query or Mutation) or field is going to be removed, it will pass through 3 consecutive phases:

1: Notice phase - 6 months

The process begins with tagging a specific field that is being deprecated. There are several ways to discover what fields have been tagged for removal:

  • Explore the docs. If an operation or field is deprecated, this information will be displayed on the doc page for the operation in question. Both operation and field level deprecations can be found here.
  • View the changelog, any deprecation notices should be found there.
  • Explore the playground. Deprecated fields will not be auto suggested by the playground. If a deprecated field is queried, a warning can be found in the response under "extensions->warnings"
  • Start looking for deprecation warnings as part of making calls to this API. More details about this can be found below in the "Programmatic Deprecation Monitoring" section.

It is suggested to stop using a deprecated field as soon as possible. It is possible for the underlying data to go stale, but will make every effort we can to not let this happen.

We then send out an email to all plans/apikeys that have been using operations that will be deprecated within a recent time period. Please make sure that the apikey(s) you're using have an email address associated with them. By doing this, we can properly notify you. To add an email address, navigate to "Manage Keys" and click the "edit" bottom on the right hand side of the apikey row and enter an email address.

2: No support phase - 3 months

After the 6 month notice phase, the operation or field in question will transition to a No Support phase for 3 additional months. This means that any modifications to the API, data integrity issues, or any changes in functionality will not be addressed.

3: Removal phase

After a total of 9 months, the operation will be removed.

Deprecation Timeline Example

  • Jan 1, 2020: query operation was marked to be deprecated.
  • June 1, 2020: query operation has entered no support mode. Any data integrity issues or other new bugs will not be addressed.
  • Sep 1, 2020: query operation will be removed. Any subsequent calls will fail.

Once phase 1 finishes, we are able to start the next batch of deprecations asyncronously with the existing process.

Changes in Alpha/Beta release stages

Beta

When a breaking change needs to be released, it will go through a similar deprecation process as was highlighted in the GR Deprecation Policy section above, but, the No Support phase will be dropped and the notice timeline will be reduced to 6 weeks.

Alpha

An operation or field marked as Alpha is subject to breaking changes with little or no warning. An effort will be made to make API users aware of breaking changes, but with no guarantee.

Programmatic Deprecation Monitoring

The best way to become aware of deprecation warnings is to look for them after every call to the API. Below is an example API call that returns an API warning:

REQUEST
Copy
{
	skillIqs (first: 2) {
	  nodes {
	    id
	    skillName
	  }
	}
      }
RESPONSE
{
	"data": {
	  "skillIqs": {
	    "nodes": [
	      {...},
	      {...}
	    ]
	  }
	},
	"extensions": {
	  "warnings": [
	    {
	      "code": "DEPRECATION_WARNING",
	      "message": "Field 'skillIqs' was deprecated on Friday, March 11th 2022. Support will cease on Sunday, September 11th 2022 and will get removed on Sunday, December 11th 2022. Query renamed. Please use 'skillAssessmentResults' instead.",
	      "path": "skillIqs"
	    }
	  ]
	}
      }

It is recommended to programmatically check the "extensions -> warnings" field in each response and output the warning or handle it in some way that is actionable.