Deprecating fields

πŸ“£ Note: This functionality will be available soon.

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:

Field Deprecation Lists in the admin
Field Deprecation Lists in the admin

Creating a new field deprecation list permalink

Click on button "Add New Field Deprecation List" to open the WordPress editor:

Creating an Field Deprecation List
Creating an Field Deprecation List

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:

Publishing an Field Deprecation List
Publishing an Field Deprecation List

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
Field deprecation

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

Access control entry
Access control entry

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.

Creating an Field Deprecation List
Selecting a field from an 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.