Extension to the GraphQL API consists of two parts:
The Shop API and Admin APIs can be extended independently:
There are a number of ways the GraphQL APIs can be modified by a plugin.
Let's take a simple example where we want to be able to display a banner in our storefront.
First let's define a new query in the schema:
This defines a new query called activeBanner which takes a locationId string argument and returns a string.
! = non-nullable
In GraphQL, the ! in locationId: String! indicates that the argument is required, and the lack of a ! on the return type indicates that the return value can be null.
We can now define the resolver for this query:
The BannerService would implement the actual logic for fetching the banner text from the database.
Finally, we need to add the resolver to the plugin metadata:
Let's continue the BannerPlugin example and now add a mutation which allows the administrator to set the banner text.
First we define the mutation in the schema:
Here we are defining a new mutation called setBannerText which takes two arguments, locationId and text, both of which are required strings. The return type is a non-nullable string.
Now let's define a resolver to handle that mutation:
Note that we have used the @Allow() decorator to ensure that only users with the UpdateSettings permission can call this mutation. We have also wrapped the resolver in a transaction using @Transaction(), which is a good idea for any mutation which modifies the database.
For more information on the available decorators, see the API Layer "decorators" guide.
Finally, we add the resolver to the plugin metadata:
If you have defined a new database entity, it is likely that you'll want to expose this entity in your GraphQL API. To do so, you'll need to define a corresponding GraphQL type.
Using the ProductReview entity from the Define a database entity guide, let's see how we can expose it as a new type in the API.
As a reminder, here is the ProductReview entity:
Let's define a new GraphQL type which corresponds to this entity:
Assuming the entity is a standard VendureEntity, it is good practice to always include the id, createdAt and updatedAt fields in the GraphQL type.
Additionally, we implement Node which is a built-in GraphQL interface.
Now we can add this type to both the Admin and Shop APIs:
Let's say you want to add a new field to the ProductVariant type to allow the storefront to display some indication of how long a particular product variant would take to deliver, based on data from some external service.
First we extend the ProductVariant GraphQL type:
This schema extension says that the delivery field will be added to the ProductVariant type, and that it will be of type DeliveryEstimate!, i.e. a non-nullable
instance of the DeliveryEstimate type.
Next we need to define an "entity resolver" for this field. Unlike the resolvers we have seen above, this resolver will be handling fields on the ProductVariant type only. This is done by scoping the resolver class that type by passing the type name to the @Resolver() decorator:
Finally we need to pass these schema extensions and the resolver to our plugin metadata:
It is also possible to override an existing built-in resolver function with one of your own. To do so, you need to define a resolver with the same name as the query or mutation you wish to override. When that query or mutation is then executed, your code, rather than the default Vendure resolver, will handle it.
The same can be done for resolving fields:
When dealing with operations that return a GraphQL union type, there is an extra step needed.
Union types are commonly returned from mutations in the Vendure APIs. For more detail on this see the section on ErrorResults. For example:
In this example, the resolver which handles the myCustomMutation operation will be returning either an Order object or a MyCustomErrorResult object. The problem here is that the GraphQL server has no way of knowing which one it is at run-time. Luckily Apollo Server (on which Vendure is built) has a means to solve this:
To fully resolve a union, Apollo Server needs to specify which of the union's types is being returned. To achieve this, you define a
__resolveTypefunction for the union in your resolver map.The
__resolveTypefunction is responsible for determining an object's corresponding GraphQL type and returning the name of that type as a string.
-- Source: Apollo Server docs
In order to implement a __resolveType function as part of your plugin, you need to create a dedicated Resolver class with a single field resolver method which will look like this:
This resolver is then passed in to your plugin metadata like any other resolver:
Sticking to this example of myCustomMutation, you'll also want to use the ErrorResultUnion in your MyCustomMutationResolver and corresponding service like so:
This is because Typescript entities do not correspond 1-to-1 with their GraphQL type counterparts, which results in an error when you're returning the Order-Object because it is not assignable to MyCustomMutationResult.
By default, Vendure bundles DateTime and a JSON custom scalars (from the graphql-scalars library). From v1.7.0, you can also define your own custom scalars for use in your schema extensions:
Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team