Leanne Shapton (@leeshapton) is a software developer at Shopify. Shopify released its public Storefront GraphQL API earlier this year. Leanne’s job was to create sample React apps that demonstrated the capabilities of Shopify’s new APIs.
This talk will cover a few things
The classic Dreyfus model of learning has 7 stages. Here is the same model simplified into 3 stages:
What’s the difference between a beginner and competent practitioner? Knowledge and context.
Beginners lack context and often feel stuck, because they don’t have enough of a mental model to do even the simplest tasks. That’s why they often require step-by-step instructions.
As a competent practitioner, you have a good enough mental model to solve normal, everyday problems. Your model might not be completely correct, but it is good enough.
As you gain experience, your mental model becomes so complex that you may not explicitly recognize each individual component of the model. As an expert, you can intuitively solve very complex issues.
They say it takes about 10,000 hours to become an expert. Today, we’re not concerned about becoming experts. Instead, we’ll focus on becoming competent practitioners with GraphQL.
Context allows learners to remember and retrieve new information because their domain knowledge is organized in a schema.
Mental models are conceptual frameworks consisting of generalizations and assumptions which we use to understand the workings of things. In the words of statistician George Box, “All models are wrong, but some are useful.”
In the remainder of this talk, we’ll focus on building a mental model of GraphQL for beginners.
Here are the key ideas understood by almost all developers regarding APIs:
Let’s start here and add GraphQL concepts on top of these.
Here are the key ideas of RESTful APIs. Some ideas are familiar to almost all devs. Others are not well understood by all or perhaps taken for granted:
Key ideas of CRUD
Here’s a common framework for a REST API:
The RESTful APIs we’re most familiar with group data by resource. Here’s an example query with our REST API:
When Leanne asked developers at Shopify what they thought were the key ideas of GraphQL, there were some ideas they could explain well and others that they couldn’t:
The foundation of the GraphQL mental model is the “graph” in GraphQL:
In addition, there are the GraphQL object types and resolvers:
When we add these concepts on top of our existing mental model, we see that GraphQL is just another interface:
An example GraphQL query:
So GraphQL fits well into the constraints we know from RESTful APIs:
What’s sometimes confusing for GraphQL beginners is that an HTTP POST request is used to query data from the server (with no mutation). That’s because they assume the RESTful mapping between CRUD operations and HTTP methods. But in the world of GraphQL, we use POST simply because we need to have a request body to dictate what data we want served to the client.
Some “Aha” moments Leanne observed in developers in the process of learning GraphQL:
Leanne has written up a detailed blog post describing the concepts and mental models in the talk.