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:
- ProgrammableWeb's 5-Part Series on Getting Started with GraphQL
- ProgrammableWeb's Hands-On Tutorial on Working with GraphQL
- Playlist of ProgrammableWeb's Companion Videos to go with KataCoda
- Downloadable source code for the IMBOB GraphQL API and Demonstration App
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

Steps
Understanding GraphQL Using IMBOB
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
cd IMBOB
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.",
"name":"PING",
"id":"ac4f1d95-88fc-4953-89b2-00b8096dec00"}}}
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.