Amara Graham

@missamarakay

I don’t need “GraphQL for Beginners” I need “GraphQL for Consumers Who Don’t Want to Use Libraries”.

01:12 AM - 18 Feb 2020

GraphQL is here, happening, and powerful, but the knowledge gap between REST APIs and GraphQL (or SOAP and GraphQL 😱) is uncomfortably large. So while some of you are happily praising how amazing and exciting GraphQL is, the rest of us are trying to work on uplifting the skills of other developers, sometimes as fast and efficiently as possible, who are left sending me these questions:

"How do I build the simplest GraphQL query in Postman?"
"What's the GraphQL syntax?"
"Is GET not a supported verb? Does GraphQL just support POST?"

You can't just npm install your way through these questions, and it is arguably worse the farther you step away from the JavaScript ecosystem. It's crucial to understand the fundamentals, but not everyone has the luxury of time. How do we consume GraphQL and harvest some of that exciting goodness?

So before we just find a library to do it for us, let's learn how to do long division by hand before we get to use a calculator. And let's learn the bare minimum just to be dangerous.

What is GraphQL?

Simply put, it is a more specifically powerful version of REST. Instead of getting a big, huge, nasty JSON object back you (overfetching) can specifically query for the data you actually want. Or maybe you have to daisy-chain a number of queries together in REST (underfetching). Fetch exactly what you need, not what you don't.

You'll see I reference both queries and mutations for examples. Queries fetch data, mutations change data.

GraphQL is way more than what I stated above, but for the purposes of this post we are going to continue approaching this from the "consumer" side.

More resources on all things GraphQL:

• https://graphql.org/learn/
• https://www.howtographql.com/
• https://developer.github.com/v4/guides/intro-to-graphql/ (maybe a little more advanced intro)

How do I form GraphQL queries?

You will find some folks saying GraphQL supports GET and POST, but in order for me to wrap my brain around this, I've committed to thinking about all of my queries as POSTs because your query is sent via a data body. For a visual, let's look at Postman body window for GraphQL.

All queries (queries and mutations) get built in JSON, and Postman, even in beta, gives us a nice place to build them.

GraphiQL is also a great way build queries and see responses. We have one for our GraphQL API, may other projects run one as well. It's a really nice pairing of a query environment and the schema, which as you get more comfortable with the rest of GraphQL you'll appreciate this more and more.

You'll notice this call is super basic, just a query for getting the release build and version.

GraphiQL is also offered in an Electron wrapper, but depending on what authentication is needed this may not work for you. Same with Insomnia. We run an HMAC digest based auth and I need to programmatically script that signature to send in the header. Neither are robust enough for that, but if you are hitting a GraphQL service with no auth or basic, you should be good either option.

Unless you are a Wowza customer with a ClearCaster, you won't be able to play with our GraphQL API or our GraphiQL environment. But you know what you could use? Your GitHub (production) data on GitHub's explorer. Be careful!

How do you use this in production?

That's not a ridiculous question at all. How do you consume GraphQL programmatically? In fact, bringing in all that experience in REST APIs might have you looking to do a quick GET in the browser URL bar.

Depending on what programming language you are working with, you'll need to build and escape your request data as you craft an HTTP POST request, which unfortunately you can't just throw into a browser's URL bar.

Let's use our Postman example.

mutation setBroadcastStatusIDLE {
  setBroadcastStatus(broadcastId: "YOURBROADCASTID", status: IDLE) {
    id
    status
    liveAt
    previewedAt
    stoppedAt
  }
}

I ran into some issues with C# and escaping double quotes, \\\ is what you are looking for.

string requestStr = "{\"query\":\"mutation setBroadcastStatusIDLE { setBroadcastStatus(broadcastId: \\\"YOURBROADCASTID\\\", status: IDLE) { id status liveAt previewedAt stoppedAt } }\"}";

For curl/bash, escaping is a little more straightforward in my opinion, just a single \.

'{"query":"mutation setBroadcastStatusLIVE { setBroadcastStatus(broadcastId: \"YOURBROADCASTID\", status: LIVE) { id \n status \n liveAt \n previewedAt \n stoppedAt } }"}'

This is one of those little annoying things that may get you stuck for days getting authorization errors or syntax errors without much to really dig into. Knowing this, we wanted to create code snippets and "gotchas" for working with our GraphQL API. It's currently a work in progress, but you get the idea.

What libraries do you recommend?

Depending on what you are trying to build, a library might be too much. Believe it or not, you don't always need an SDK either.

At this point, I'm still working through vetting potential libraries I would recommend. I'm looking for libraries that appear to be well supported (if they are open source, many are) and robust.

If you have libraries that you recommend for querying GraphQL APIs in python, C#, node, php, etc. I'd love to hear about them in the comments!

Are you consuming GraphQL? How is it going? Did you come from a REST background?