6 min to read

Sitecore JSS: Create your own GraphQL schema

Featured image

One very great feature is added to the Sitecore JSS module: GraphQL support. It allows you to query an API with a JSON payload. Compared to REST API's GraphQL is more maintainable and more flexible as GraphQL services can be stiched together.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.

Building the Sitecore GraphQL SchemaProvider

In this post I will walk through the following steps to guide you setting up a custom GraphQL SchemaProvider from which you can query the enpoint.

Steps to create your own GraphQL schema in Sitecore:

The first step is to look at the example on the JSS website under the Techniques section. I have based my code on this example to keep it as simple as possible. When I wrote this post GraphQL was installed via installing JSS, but it should be available separately at launch (probably Oct. 2018).

First you need to set <compilation debug="true"> in web.config enabling the GraphQL UI. If you already have been playing around with JSS you also have an SSC API key in place in de Core Database. If not, make sure to do so.

Setting up the GraphQL configuration in Sitecore

On the JSS website the configuration is just an example (but not a working one). Below is a working example of the schema we are building. We need to do two things to make t work:




</code></pre>


Creating a SchemaProvider

{: id="creating-a-schemaprovider"}


For this example I created a class library. When I started developing the SchemaProvider I wanted to expose data from The Movie Database For this I use the TMDbLib Nuget package. After building my library I copied the dll to the bin folder of my website's webroot.


Source for the SchemaProvider class:

{: id="source-for-the-schemaprovider-class"}



using System;
using System.Collections.Generic;
using System.Web;
using GraphQL.Resolvers;
using GraphQL.Types;
using Sitecore;
using Sitecore.Security;
using Sitecore.Security.Accounts;
using Sitecore.Services.GraphQL.Schemas;
using TMDbLib.Client;
using TMDbLib.Objects.Movies;

namespace Macaw.GraphQL.Examples
{
    class MovieSchemaProvider : SchemaProviderBase
    {
        public override IEnumerable CreateRootQueries()
        {
            yield return new MovieQuery();
        }
        protected class MovieQuery : RootFieldType<MovieGraphType, Movie>
        {
            public MovieQuery() : base(name: "movieQuery", description: "Gets some movie data")
            {
                QueryArgument[] queryArgumentArray = new QueryArgument[1];
                int index1 = 0;
                QueryArgument queryArgument1 = new QueryArgument();
                queryArgument1.Name = "movieId";
                queryArgument1.Description = "The movie ID to get";
                queryArgumentArray[index1] = (QueryArgument)queryArgument1;

                this.Arguments = new QueryArguments(queryArgumentArray);
            }
            protected override Movie Resolve(ResolveFieldContext context)
            {
                int movieId = context.GetArgument("movieId", (int)383498);

                TMDbClient client = new TMDbClient("APIKEY");
                Movie movie = client.GetMovieAsync(movieId, MovieMethods.Credits | MovieMethods.Similar).Result;
                return movie;
            }
        }
        protected class MovieGraphType : ObjectGraphType
        {
            public MovieGraphType()
            {
                Name = "TMDbLibMovie";

                Field<NonNullGraphType>("id", resolve: context => context.Source.Id);
                Field<NonNullGraphType>("title", resolve: context => context.Source.Title);
                Field< ListGraphType< KeywordGraphType >>("keywords", resolve: context => context.Source.Keywords.Keywords);
                Field<NonNullGraphType>("posterpath", resolve: context => context.Source.PosterPath);
                Field<NonNullGraphType>("overview", resolve: context => context.Source.Overview);
                Field<NonNullGraphType>("backdropPath", resolve: context => context.Source.BackdropPath);
                Field<NonNullGraphType>("budget", resolve: context => context.Source.Budget);
                Field< ListGraphType < GenreGraphType >> ("genres", resolve: context => context.Source.Genres);
                Field<NonNullGraphType>("releaseDate", resolve: context => context.Source.ReleaseDate);
                Field<NonNullGraphType>("voteAverage", resolve: context => context.Source.VoteAverage);
                Field<NonNullGraphType>("voteCount", resolve: context => context.Source.VoteCount);
            }
        }
        protected class GenreGraphType : ObjectGraphType
        {
            public GenreGraphType()
            {
                Name = "TMDbLibMGenre";
                Field<NonNullGraphType>("id", resolve: context => context.Source.Id);
                Field<NonNullGraphType>("title", resolve: context => context.Source.Name);
            }
        }

        protected class KeywordGraphType : ObjectGraphType
        {
            public KeywordGraphType()
            {
                Name = "TMDbLibMKeyword";
                Field<NonNullGraphType>("id", resolve: context => context.Source.Id);
                Field<NonNullGraphType>("title", resolve: context => context.Source.Name);
            }
        }
    }
}

</code></pre>



NOTE: this example is using nested classes because it's a very very small schema. A real schema of any size should split the RootFieldTypes and GraphTypes into separate files.




Adding arguments

{: id="adding-arguments"}


By default our Query class won't accept any attributes like the movieId in our example. We accomplish this by adding QueryArguments in the contructor of the Query. These are used in the Resolve method where we can get the arguments like in our example: int movieId = context.GetArgument<int>("movieId", (int)383498);


GraphQL FieldTypes

{: id="graphql-fieldtypes"}


By default we will retrieve the field values as a string. In many cases we need to use other types like booleans, floats, lookups etc. For our demo I constructed two custom GraphTypes and constructed a ListGraphType from this. The result is that I now can also query the genres of the movie rather than getting an exception when querying the field.


Quering the GraphQL API

{: id="quering-the-graphql-api"}


Now we have deployed our schema and configuration we now can test it. In the configuration I added the url /sitecore/api/graph/items/movies. Hiting the url will now result in the following error: {"errors":[{"message":"SSC API key is required. Pass with 'sc_apikey' query string or HTTP header."}]}. This is because my example forces you to provide the SCC API key. This can be done by adding ?sc_apikey={YOUR_API_KEY} in the querystring. Adding /ui will show the Sitecore Experience Graph Browser.




From here you can test your queries. In the given example I added a movie query:



{
  movieQuery(movieId: "353081") {
    id,
    title,
    posterpath,
    overview,
    budget,
    genres {
      id,
      title
    }
    releaseDate,
    voteAverage,
    voteCount
  }
}	



After firing the query we now get results:




The query is created with ease. Intelisense will help us construct the query. On the right side we can inspect the schema and find all available fields we can access. Happy coding :)