Learning Through APIs

I found an old GraphQL workshop I wrote almost ten years ago.

Some of it has aged exactly how you'd expect a ten year old technical workshop to age. Old screenshots. Old setup instructions. A few things I would definitely explain differently today.

But going through it again reminded me of how fun it is to break something down and learn a new technology. For myself or for others.

Start with the problem

How does an app get information from somewhere else

The workshop started with APIs and REST before getting anywhere near GraphQL. An application makes a request, another system sends something back, and the application uses that response.

REST gave us a familiar starting point: resources, URLs and JSON. From there, we could ask what GraphQL changes about that conversation.

PowerPoint slide from the original GraphQL workshop explaining REST APIs and JSON responses. — REST APIs and JSON responses.

Ask for what you need

PowerPoint slide from the original GraphQL workshop introducing GraphQL with a query and its response. — An early GraphQL query and response.

One of the ideas I wanted to make clear was that GraphQL lets the application describe the information it needs. If I only need a name and height, those are the fields I can ask for.

That becomes much easier to understand when you can see the request and response together. The structure of what comes back follows the structure of what was requested.

The request shapes the response

This was one of the concepts I wanted someone to be able to see, not just memorize.

The workshop broke the two sides apart. First, build a query asking for a user's name, email and birthday. Then look at the response and find those same fields coming back in the same structure.

PowerPoint slide from the original GraphQL workshop showing a query requesting a user's name, email, and birthday. — The query asks for three fields.

PowerPoint slide from the original GraphQL workshop showing the response containing the requested name, email, and birthday. — The response follows the same shape.

Then we started poking at it.

Once the basics made sense, the workshop stopped giving away as much. We used the schema and documentation to figure out what the API could give us: products, titles, images and variants.

At one point we asked for products and got an error because the API needed a first or last argument. So we read the error, looked at the documentation and changed the query to products(first: 4).

I like that part looking back at it. I wasn't jus trying to get folks to copy a finished query. It was to get comfortable figuring out why something didn't work and what to try next.

I still learn this ways

The workshop eventually went further into queries, mutations and using information from one request in the next. The technology was the subject, but learning how to explore it was just as important.

I still tend to approach unfamiliar technology the same way: build something, poke at it, read the documentation, break a few things and keep going until the pieces make sense.

← Back to Reflections