Difficulty: beginner
Estimated Time: 30 minutes

This Katacoda-based interactive tutorial is a companion element ProgrammableWeb's Guide to GraphQL: Understanding, Building and Using GraphQL APIs. That guide is a comprehensive five part series designed to bring API practitioners at any level (beginner, intermediate, or advanced) up to speed on GraphQL as a technology and how to work with it. The series includes source code that can be found in a freely copyable open source code repository. There are also eight videos that ProgrammableWeb has published on its YouTube channel that are embedded in this interactive learning environment.

Here are links to the key elements of this special package:

Table of Contents

  • Educational Objective
  • What To Expect
  • What You Need To Know Before You Start
  • Working with GraphQL and IMBOB
  • Scenario Contents

IMPORTANT: You need to do the steps in sequence in order for the state of the lesson's learning environment to be consistent. Otherwise, you'll get behaviors that might be confusing.

Educational Objective

The purpose of the scenario is to present the demonstration GraphQL API, IMBOB and to show users how to perform the following queries and mutations against the IMBOB demonstration API. Also the scenario shows you how to use GraphQL subscriptions and directives.

What To Expect

After taking this scenario you will be able to:

  • To install the IMBOB API in the Katacoda interactive learning environment
  • To access an instance of Apollo Server GraphQL Playground bound to the IMBOB API running in the Katacoda interactive learning environment
  • To use to the interactive schema documentation published GraphQL Playground
  • To learn about the details of the IMBOB API using GraphQL introspection
  • To create and implement queries and mutations in GraphQL Query Language against the IMBOB API
  • To register subscriptions to the IMBOB API and receive messages asynchronously upon execution of certain mutations
  • To apply a GraphQL directive to a mutation in executed against the IMBOB API

What You Need To Know Before You Start

In order to get full benefit from taking this scenario it's useful to have a working understanding of the syntax of the GraphQL Query Language. Also it's good to have an understanding of the basics GraphQL operations of query, mutation and subscription.

Working with GraphQL and IMBOB

This scenario published a custom built API, IMBOB. IMBOB is a GraphQL API built using Apollo Server. IMBOB publishes data that presents some basic movie information. The API is scaled back to show data for only a few movies.

The reason only a few movies are represented is to provide just enough related data thus enabling the underlying object graph to make sense in term of organization and association.

Please be advised that the IMBOB API does provide mutations that allow users to build out the underlying object graph. However, if a mishap occurs, all that required to set the scenario and IMBOB to its initial state is to refresh this web page.

Source Code

The source code for the IMBOB demonstration GraphQL API used in this scenario can be found on GitHub here .

Scenario Contents

Step 1 - Setting Up The GraphQL API to Run on Katacoda

Step 2 - Accessing and Authenticating to the API

Step 3 - Executing Sample GraphQL Queries

Step 4 - Registering a Subscription

Step 5 - Firing a Subscription Event using the Mutation, Ping

Step 6 - Working with onMovieAdded to Add Data and Generate Asynchronous Messages

Step 7 - Declaring a Restricted Field Using a Custom Directive

Step 8 - Working with Connections

Last revised: 08-01-2019

You've crossed the finish line!

In this scenario you learned:

  • How to setup the GraphQL API, IMBOB, to run under Katacoda
  • How to access and authenticate IMBOB using an authentication token
  • How to execute simple and paginated queries
  • How to register to a custom subscription running on IMBOB in order to receive messages
  • How to execute a mutation that emits a message to a subscription
  • How to execute mutations against a more complex subscription
  • How design time directives work
  • How to work with connections to get data related to an entity in IMBOB

Understanding GraphQL Using IMBOB

Step 1 of 8

Step 1 - Setting Up The GraphQL API to Run on Katacoda

This introductory video covers the tasks you'll perform in this step.

Let's set up the GraphQL API.

Task 1: Get the code from GitHub:

git clone https://github.com/programmableweb/IMBOB.git

Task 2: Go to the folder that has the source code and Dockerfile


Task 3: Make the Docker image that represents the GraphQL API

docker build -t imbob .

Task 4: Now, create the container

docker run -d -p 80:4000 imbob

Let's check to see that the GraphQL API is up and running

Task 5:: Click the following command the verify that the GraphQL API is up and running.

curl 'http://localhost:80/' -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Connection: keep-alive' -H 'DNT: 1' -H 'Origin: http://localhost:80' -H 'authorization: ch3ddarch33s3' --data-binary '{"query":"mutation{\n ping(messageBody: \"This is a simple message body.\"){\n createdAt\n body\n name\n id\n }\n}"}' --compressed

If all is well you should see a response similar to the following (id and createdAt values will differ by installation.):

{"data":{"ping":{"createdAt":"Sun May 12 2019 15:41:37 GMT+0000 (Coordinated Universal Time)",
         "body":"This is a simple message body.",

Understanding This Step

The purpose of this step was to get the IMBOB API server up and running so that we can experiment with GraphQL queries, mutations and subscriptions.

In the next step we'll be working the GraphQL Playground web page that ships with Apollo server to do work.