Creating a custom endpoint

The GraphQL API for WordPress, in addition to the single endpoint, also supports custom endpoints, to retrieve and post data for a custom schema (containing only a subset of the available types) and user validation rules, as to deal with the needs from different users and applications.

We can create as many custom endpoints as needed.

For instance, we can create a custom endpoint for:

  • Some specific client or user, under /graphql/my-client/
  • A group of users with more access to features (such as PRO users), under /graphql/pro-users/
  • Provide data to our mobile app, under /graphql/mobile-app/
  • Give access to some 3rd-party API, under /graphql/external-api/
  • Others

Accessing all custom endpoints permalink

Clicking on "Custom Endpoints" on the plugin's menu, it displays the list of all the created custom endpoints:

Custom Endpoints in the admin
Custom Endpoints in the admin

Creating a new custom endpoint permalink

Click on button "Add New GraphQL endpoint" to open the WordPress editor:

Creating a new Custom Endpoint
Creating a new Custom Endpoint

Give it a title, make sure the permalink is the desired one, select the schema configuration, and adjust the options. When ready, click on the Publish button, and the custom endpoint is created, using the configured permalink as endpoint URL:

Publishing the custom endpoint
Publishing the custom endpoint

Schema configuration permalink

Defining what elements the schema contains, and what access will users have to it, is defined in the schema configuration.

So we must create a create a schema configuration, and then select it from the dropdown (or use none, or the default one):

Selecting the schema configuration
Selecting the schema configuration

Creating an endpoint hierarchy permalink

Please read the instructions on creating an API hierarchy.

Disabling the custom endpoint permalink

In the options, set "Enabled" to false to disable the custom endpoint.

This feature can be useful when making the custom endpoint be part of an API hierarchy, to provide a common behavior to its child custom endpoints, but without needing itself be executed.

Describing the custom endpoint permalink

Use the "Excerpt" field, from the Document settings panel, to give a description to the custom endpoint.

Find more information in guide Adding a description to the API.

Executing the custom endpoint permalink

Once the endpoint is published, we can execute queries against it via its permalink.

When opening a custom endpoint in the browser, we will get a JSON response, containing message "The query in the body is empty":

Opening a custom endpoint in the browser
Opening a custom endpoint in the browser

This is right. The message indicates that we need to submit a query to it, to get the response.

Executing the custom endpoint in an application permalink

Please follow the instructions on guide Executing queries against the GraphQL server.

Endpoint clients permalink

Each custom endpoint has its own set of clients to interact with.

GraphiQL client permalink

Add ?view=graphiql to the endpoint to access its GraphiQL client:

Custom endpoint's GraphiQL client
Custom endpoint's GraphiQL client

To disable it, set option "Expose GraphiQL client?" to false.

Voyager client permalink

Add ?view=schema to the endpoint to access its Voyager client, to visualize and interact with the endpoint's schema:

Custom endpoint's Voyager client
Custom endpoint's Voyager client

To disable it, set option "Expose the Interactive Schema client?" to false.

Viewing the source permalink

Appending ?view=source to the endpoint, it will show the endpoint's configuration (as long as the user has access to it):

Custom endpoint source
Custom endpoint source


Configuration in the WordPress editor permalink

These are the inputs in the body of the editor:

InputDescription
TitleCustom endpoint's title
Schema configurationFrom the dropdown, select the schema configuration that applies to the custom endpoint, or one of these options:
  • "Default": the schema configuration is the one selected on the plugin's Settings
  • "None": the custom endpoint will be unconstrained
  • "Inherit from parent": Use the same schema configuration as the parent custom endpoint.
    This option is available when module "API Hierarchy" is enabled, and the custom endpoint has a parent query (selected on the Document settings)
OptionsCustomize the behavior of the custom endpoint:
  • Enabled?: If the custom endpoint is enabled.
    It's useful to disable a custom endpoint it's a parent query in an API hierarchy
  • Expose GraphiQL client?: Enable/disable attaching a GraphiQL client to the endpoint, accessible under ?view=graphiql
  • Expose the Interactive Schema client?: Enable/disable attaching an Interactive schema client to the endpoint, accessible under ?view=schema
  • Inherit query from ancestor(s)?: Use the same query as the parent custom endpoint.
    This option is available when module "API Hierarchy" is enabled, and the custom endpoint has a parent query (selected on the Document settings)

These are the inputs in the Document settings:

InputDescription
PermalinkThe endpoint under which the custom endpoint will be available
CategoriesCan categorize the custom endpoint.
Eg: mobile, app, etc
ExcerptProvide a description for the custom endpoint.
This input is available when module "Excerpt as Description" is enabled
Page attributesSelect a parent custom endpoint.
This input is available when module "API Hierarchy" is enabled