Introduction to GraphQL

ePublishing has a powerful GraphQL API that you can use to read or write to ePublishing's database for your site. Example use cases: 

  • Output all of your taxonomies
  • Importing directories, articles, or users
  • See which users created accounts based on creation date 

What is GraphQL and GraphiQL?

  • GraphQL  is a query language for APIs and a runtime for fulfilling those queries. GraphQL provides a complete and understandable description of the data in our API and gives you the power to ask for exactly what you need and nothing more. If you want to learn more about GraphQL check out graphql.org.

  • GraphiQL is a graphical interactive in-browser GraphQL integrated development environment. You can use it to read or change your site's database with the GraphQL language.  

Queries and Mutations

Part of learning any new tool is learning the nomenclature.

In GraphQL you write queries to read from the database. A GraphQL query is essentially a tree that declares the data you are looking for, such as all users created after a date. When you submit a query with GraphiQL  the output is the data  matching the specifications of  your query. The input is in the GraphQL language and the output is  in JSON (JavaScript Object Notation).

Mutations are GraphQL expressions to change the database.

So queries are for extracting data and mutations are for adding, updating, and deleting data.

Please note queries are still in beta and mutations are in early alpha - so issues are likely present. 

See an example of a query below. The query can be entered on the left hand GraphiQL pane. After the query is created, clicking the arrow runs the query and outputs the data on the right hand pane as JSON.

# The JSON output is paginated. Most sites have a maximum 100 records 
# per type per query. To see pages other than the first one specify 
# the page argument in the list field. This example below specifies 
# page 3 of the list of all users.

query SampleQuery {
  users(page: 3) {
    id
    email
    oid
    live
  }
}

See the example of the mutation below. In GraphiQL the mutation entered in the left hand pane, as with a query. After the mutation is created, click the arrow to post the mutation and change your site's database.

# This mutation example creates a new article. The data for the 
# article is in the $input variable, which can be added in the lower 
# left "Query Variables" pane of GraphiQL or provided in the post 
# request parameters as a variables hash. This mutation returns the 
# id of the newly created article, plus a boolean success flag and a 
# list of any errors.

mutation ($input: ArticleCreateInput!) {   
  articleCreate(input: $input)            
  {                                                      
    article { id }                                                    
    success                                              
    errors                                               
  }                                                      
}

You can access GraphiQL on both your staging and production sites.

  • To see the documentation defining the fields and specifying which fields you can use to sort and filter for each content type, add /query/docs to either your staging or production URL.
    • For example: https://www.yourdomain.com/query/docs
  • To see example queries and mutations, add /query/docs/examples to your staging or production URL.
    • For example: https://www.yourdomain.com/query/docs/examples
  • If you just want to do a query or mutation,  add /query/graphiql to either your staging or production URL.
    • For example:  https://www.yourdomain.com/query/graphiql

What fields can I filter and sort the main content types by?

Adding a filter to your query with filterString helps you refine your query to narrow down the results. For example if you want to output only users created after a date you could query for

 users(filterString: "createdAt > 2019-03-01") { email } 

To see which fields the main content types -- such as users, articles, and events -- can be filtered by,  see the documentation for Query type,  found at /query/docs/operation/query. In GraphiQL documentation is also available in the Docs dropdown on the top right.

Tips for Learning GraphQL

  • Relax and take your time. 
  • Focus on one content type at a time such as articles or users. 
  • Start with the example queries. 
    • When first learning queries, starting a query from scratch can be more challenging then tweaking an example query. You can find example queries at /query/docs/examples
  • Start with queries and then take on mutations.
  • Take advantage of GraphiQL auto suggestions.
  • Learn the syntax of GraphQL. This will become second nature as you increase your skills. Here are some handy tips to get you started. 
    • You need the same number of closing curly braces as you have opening curly braces.
    • Field names are mixed case with the pattern of lowercaseUppercase. For example, updatedAt 
    • The syntax for an argument is parenthesis, argument name, colon, space, argument value, and closing parenthesis. 
      • For example: articles(page: 2) { title }
    • The syntax for a filter with only a single criteria is parenthesis, filterString, colon, space, quotation mark, field, space, qualifier, quotation mark,  and closing parenthesis. 
      • For example:  users(filterString: "createdAt > 2019-02-01"){ email }
    • The syntax for a filter with more than one criteria is parenthesis, filterString, colon, bracket, quotation mark, field, space, qualifier, quotation mark, comma, quotation mark, field, space, qualifier, quotation mark, bracket, parenthesis. 
      • For example: articles(filterString: ["postAt < 1 year ago", "active isNotNull"]) { title }