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:
Creating a new custom endpoint permalink
Click on button "Add New GraphQL endpoint" to open the WordPress editor:
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:
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):
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":
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:
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:
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):
Configuration in the WordPress editor permalink
These are the inputs in the body of the editor:
| Input | Description |
|---|---|
| Title | Custom endpoint's title |
| Schema configuration | From the dropdown, select the schema configuration that applies to the custom endpoint, or one of these options:
|
| Options | Customize the behavior of the custom endpoint:
|
These are the inputs in the Document settings:
| Input | Description |
|---|---|
| Permalink | The endpoint under which the custom endpoint will be available |
| Categories | Can categorize the custom endpoint. Eg: mobile, app, etc |
| Excerpt | Provide a description for the custom endpoint. This input is available when module "Excerpt as Description" is enabled |
| Page attributes | Select a parent custom endpoint. This input is available when module "API Hierarchy" is enabled |