Experimental fields - Redo

Some fields and types in the v3 API are experimental. They work and are supported, but their shape may change, or they may be removed, without notice or a deprecation period. They’re marked (Experimental) in this reference and @experimental in the schema.

Opting in

To use an experimental field, add @experimental to it in your query:

query {
  automations @experimental {
    nodes {
      id
      name
    }
  }
}

The directive covers everything inside the field, so the fields of an experimental type need no directive of their own. When an experimental type is reached through a stable interface such as Node, put the directive on the fragment instead:

query {
  node(id: "aut_123") {
    ... on Automation @experimental {
      name
    }
  }
}

A query that uses an experimental field without opting in fails validation:

{
  "errors": [
    {
      "message": "Query.automations is experimental and may change or be removed. Add @experimental to use it.",
      "extensions": { "code": "EXPERIMENTAL_OPT_IN_REQUIRED" }
    }
  ]
}

When a field becomes stable

Once an experimental field is stable, it follows the same compatibility rules as the rest of the API. You don’t need to change your queries: @experimental on a stable field is accepted and ignored.