Note: Module "Field Deprecation" must be enabled to use this functionality (it is disabled by default). Check in guide Browsing, enabling and disabling modules on how to enable it.
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, the GraphQL API for WordPress 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 permalink
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 permalink
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:
Field Deprecation entries permalink
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 permalink
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.