What you'll learn
- the two separate GraphQL APIs that are included by default in every Webiny project
- how to use the
GraphQLSchemaPluginin order to extend an existing GraphQL API
When it comes to HTTP API development, Webiny relies on GraphQL. In fact, all of the applications that are part of the Webiny Serverless CMS, for example Page Builder or Headless CMS, are using it in order to enable developers programmatic interaction via a client of their choice, for example a browser.
By default, every Webiny project starts off with two separate GraphQL APIs.
The default GraphQL API (or just GraphQL API) is the GraphQL API that's located within the
api/code/graphql folder. All of the Webiny Serverless CMS applications are built on top of it, and, in the same fashion, the API can be extended by developers, if need be.
The Headless CMS GraphQL API is a special standalone GraphQL API that is introduced by the Headless CMS application. It's located in the
api/code/headlessCMS folder and, like the default GraphQL API, can also be extended by developers.
Learn more about the Headless CMS GraphQL API.
In general, when talking about extending an existing GraphQL API, we're usually referring to one or more of the following:
- adding new query or mutation GraphQL operations
- adding new GraphQL types
- extending existing GraphQL types with additional fields
For example, we might want to add a new, Page Builder-related,
duplicatePage mutation, that would be responsible for making copies of provided pages. Or, we might just want to add an extra field to the
PbPage GraphQL type, so that we can store some additional data for each page.
And although, depending on the application and the change we want to perform, some of the steps in the overall GraphQL extension process may differ, in all cases, we will want to start by registering a new
The plugin is registered within your GraphQL API's application code. For example, if we wanted to extend the default GraphQL API, we would create the plugin inside of the
api/code/graphql/src/plugins folder, and register it in the
api/code/graphql/src/index.ts entrypoint file. On the other hand, if we wanted to extend the Headless CMS GraphQL API, we would create the plugin inside of the
api/code/headlessCMS/src/plugins folder, and register it in the
api/code/headlessCMS/src/plugins/index.ts entrypoint file.
The following is an example of a simple
GraphQLSchemaPlugin plugin that extends the default GraphQL API with a new
Having the plugin registered within the default GraphQL API's application code (in the mentioned
api/code/graphql/src/index.ts entrypoint file), we should be able to see and execute the
listBooks query, for example via the API Playground:
Executing the query should give us the following result:
For more concrete examples, you can also visit the following guides which explain how to extend GraphQL types and operations that belong to different Webiny applications: