Schema lifecycle

How are fields created and deleted from our graphQL API

Note In this section, fields, queries and mutations will all be called “field” as queries and mutations are special cases of fields.

In the context of our GraphQL API, a field has the following lifecycle:

1. The field is (optionally) created under a preview

2. The field is made generally available

3. The field is deprecated

4. The field is removed from the API

Preview

Similarly to how our product has some features in beta (during which we correct and improve the feature), our GraphQL API has some fields under preview. This allows the consumers of our API to benefit from the feature as early as possible, while we gather feedback in order to fix or improve the feature.

While under preview, a field is susceptible to change in behaviour to accommodate for the development of the feature and best cater to your needs. A field that was created under preview will stay under preview for 6 months.

In order to access fields that are under previews, the Accept header of the GraphQL HTTP request must contain application/vnd.iadvize.<preview-name>-preview+json where preview-name is replaced by the name of the feature, as given to you by your iAdvize contact.

This is a equivalent to what Github has developed with their own API.

In order to monitor the usage of previews, we don't list previews available in the Graphql API. If your project requires specific capabilities, your iAdvize contact may give you field names and their respective preview names.

General Availability

Once a field is considered stable, it is made generally available. This is the default state of a field, where it is visible in the public documentation. A generally available field is expected to remain stable: no breaking change are expected to be introduced.

Deprecation

Our product is in constant evolution, and although we strive to achieve stability, sometimes it is essential to reconsider the usefulness of some of the fields exposed through our API. In such cases we'll mark a field as being deprecated. The deprecation process is the following:

1. We mark the field as being deprecated

2. A minimum of 1 year of maintenance of the feature is guaranteed from that point on

3. The field will then be deleted in the next "breaking release"

Removal (Breaking releases)

In order to limit the amount of adaptations a client might have to implement in a given year, we batch every modification susceptible to introduce a break in backward compatibility into "breaking releases".

We have two such releases per year: the first Monday of October, and the first Monday of April.

Shortly after these dates we'll release new versions or our API that will remove the fields that have been deprecated for more than a year.