Deprecating fields
Versioning a GraphQL schema involves deprecating fields, i.e. telling the user that the field should not be used anymore, and what other field to replace it with.
In addition to deprecating fields through code, Gato GraphQL provides a user interface to configure what fields to deprecate, and how.
The configuration is created through a field deprecation list, and delivered to custom endpoints and persisted queries via the schema configuration.
Accessing all field deprecation lists
Clicking on "Field Deprecation Lists" on the plugin's menu, it displays the list of all the created field deprecation lists:
Creating a new field deprecation list
Click on button "Add New Field Deprecation List" to open the WordPress editor:
Give the field deprecation list a title, add entries with fields, and configure the deprecation message. When ready, click on the Publish button. Then, the new field deprecation list becomes available to the schema configuration.
The field will be marked as deprecated in the schema and, in addition, the deprecation message will be displayed in the response when querying a deprecated field (if module Deprecation Notifier is enabled).
Field Deprecation entries
Every Field Deprecation List contains one or many entries, each of them with the following elements:
- The fields to deprecate
- The deprecation message
Selecting fields from interfaces
In addition to fields from types, we can also select fields from interfaces. In this case, the deprecation is executed on these fields from all types implementing the interface.
Describing the field deprecation list
Use the "Excerpt" field, from the Document settings panel, to give a description to the field deprecation list.
Find more information in guide Adding a description to the API.
Using the field deprecation list
After creating the field deprecation list, we can have the Custom Endpoint or Persisted Query use it by editing the corresponding Schema Configuration, and selecting the ACL from the list under block "Field Deprecation Lists".
If not customizing the configuration, the default Field Deprecation Lists defined on the Settings page, under tab "Field Deprecation", will be used:
