Consuming GraphQL Simply
Get Started Without a Consumer Library
I’ve recently found myself once again building an API gateway service — a server which provides to consumers a cohesive, unified interface to a suite of specialized backend concerns. The first official client is a mobile app, and early in the project we decided GraphQL seemed an ideal interface with the phone. No one on our team had practical experience with it, so we decided to make GraphQL an eventual ideal.
GraphQL provides a number of benefits to a service like the one I’m building. It forces you to think about your data entities and their relationships up front. It allows the API consumer expressive flexibility in deciding what it wants, without worrying overmuch about which resources are where.
The GraphQL schema providing library I’m using in the server provides tools to map nodes in the graph to resolvers which are responsible for getting what’s needed when it’s needed without complication. I recently started migrating much of the gateway service’s internals over to resolvers, and making the REST endpoints execute GraphQL under the hood. It’s been such a great experience it’s how I want to build any REST APIs in the future.
I setup an instance of GraphiQL to demo the new API. But while working with the mobile team to transition from our ad-hoc REST endpoints to using the new technology, there’s not a lot of resources to understand how to work with a GraphQL API aside from, just use a library. While that might be a good idea, the popular libraries tend to be quite heavyweight, solve problems not common to all implementations of GraphQL (including ours), and tend to be prescriptive about client-side state management.
If you just want to understand how to work with it there’s not a lot of beginner-friendly info. The documentation can be a bit abstract at times, and often conflates the topics of providing, consuming, resolving and responding to GraphQL queries. GitHub has a good guide, but unless you’re working with their API it’s not apparent that their resource is a general one.
Let’s get started by making some simple queries against GitHub’s extensive GraphQL API and API Explorer using GraphiQL, let’s make some simple queries. Any demo involving HTTP ought to provide examples using curl.
First, create a personal token for use on the command-line. In the examples below, this will be $TOKEN
. I’ll prettify the results a bit. Let’s use GitHub’s example query to see if it works:
whoami
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"query { viewer { login }}"}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \"query { viewer { login }}\" }" \
https://api.github.com/graphql
query { viewer { login }}
{ "data": {
"viewer": {
"login": "mattly" }}}
Indeed it did! A few things for your attention:
-
The query is a POST request with a JSON body. This is standard for GraphQL over HTTP. Don’t argue about REST semantics here — POST is for the query because it might be too large to fit in url query parameters.
-
The query is a string at the
query
field inside the request body. The API server will parse the string into the query structure. -
The query body is not valid JSON. GraphQL queries are their own language and many editors can highlight them specially.
-
The data we wanted
[queryRoot viewer login]
is in the response body at thedata
key.
While that covers the basics, you really should know about variables, mutations, and errors.
A GraphQL schema can declare that a field takes arguments, and sometimes those arguments are required for certain things. For example, if I wanted to list my top repositories, GitHub requires me to specify how many I want per-page via a field argument:
popular repos
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"query {
viewer {
repositories(
first: 3,
orderBy: { field: STARGAZERS, direction: DESC }
) { nodes { name }}}}"}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \
\"query { \
viewer { \
repositories( \
first: 3, \
orderBy: {field: STARGAZERS, direction: DESC}) \
{ nodes { name }}}}\" }" \
https://api.github.com/graphql
query {
viewer {
repositories(
first: 3,
orderBy: {
field: STARGAZERS,
direction: DESC }) {
nodes {
name }}}}
{ "data": {
"viewer": {
"repositories": {
"nodes": [
{ "name": "vim-colors-pencil" },
{ "name": "bork" },
{ "name": "iterm-colors-pencil" }]}}}}
In the repositories
field, I’m telling it I want the first four, ordered by the number of stars. The first
field is required by this API, and orderBy
defaults to the creation time. I found all this out by looking at GitHub’s GraphiQL Explorer and poking around at the documentation (generated by introspection on the schema) on the right of the interface. It also told me that orderBy
is a RepositoryOrder
object, which has two fields, both of which whose possible values are part of an enumerated, finite set.
On the other hand, if I only want to know how many repositories I have without knowing anything else about them, I don’t have to provide a count:
total repo count
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"query { viewer { repositories { totalCount }}}"}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \
\"query { \
viewer { \
repositories { totalCount }}}\"}" \
https://api.github.com/graphql
query {
viewer {
repositories {
totalCount }}}
{ "data": {
"viewer": {
"repositories": {
"totalCount": 43 }}}}
Requiring a value for the repositories
field or not is a requirement the server enforces based on whether you’re reaching further into the nodes on that part of the graph.
A useful feature of GraphQL is variables. If you wanted to query for any given person’s top-starred repositories, you could construct such a query with string concatenation. Or perhaps a dynamic GraphQL query-generation library. You shouldn’t — you should use variables instead.
variables
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"query UserMostStarredRepos($user: String!) {
user(login: $user) {
repositories(
first: 3,
orderBy: { field: STARGAZERS, direction: DESC }) {
nodes { name stargazers { totalCount }}}}}",
"variables": {"user": "mattly"}}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \
\"query UserMostStarredRepos(\$user: String!) { \
user(login: \$user) { \
repositories( \
first: 3, \
orderBy: {field: STARGAZERS, direction: DESC}) \
{ nodes { name stargazers { totalCount }}}}}\",
\"variables\": {\"user\": \"mattly\"}}" \
https://api.github.com/graphql
query UserMostStarredRepos($user: String!) {
user(login: $user) {
repositories(
first: 3,
orderBy: {
field: STARGAZERS,
direction: DESC }) {
nodes {
name stargazers { totalCount }}}}}
{ "data": {
"user": {
"repositories": {
"nodes": [
{ "name": "vim-colors-pencil",
"stargazers": { "totalCount": 344 }},
{ "name": "bork",
"stargazers": { "totalCount": 211 }},
{ "name": "iterm-colors-pencil",
"stargazers": { "totalCount": 104 }}]}}}}
There’s a few new things here:
-
I gave a operation name for the query —
UsersMostStarredRepos
— along with variables for it. The variable,user
is a string, and must be present (that’s what the!
means). Adding an operation name is required when you have variables. -
I used this variable in the arguments to the
user
field. -
There’s a
variables
value in the request body which is a JSON object.
Eventually you’ll want to submit changes to the API. In the REST world, we have a number of ways to do that: POST
, PUT
, and since some people were being a little too pedantic about that behavior we have PATCH
, and of course DELETE
.
But rarely have I met an API that sticks to the straight semantics behind these REST verbs. People bend the rules such that “REST” becomes RPC over HTTP. GraphQL offers a better way with mutations. And they’re not very different from what we’ve seen so far:
-
Mutations don’t use the
Query
root but ratherMutation
root, and so have different entry points from regular queries. -
If you provide multiple mutations in a single query, they are performed in the order given in the query.
-
Mutations take input via arguments, and return objects, from which you must select at least one field.
This query will do one new thing though, use an inline fragment to select fields on a Union Type:
mutations
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"mutation StarRepo($id: ID!) {
addStar(input: {starrableId: $id}) {
starrable {
... on Repository { name }
viewerHasStarred
stargazers { totalCount }}}}",
"variables": {"id": "MDEwOlJlcG9zaXRvcnkxMDg4OTA0MA=="}}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \
\"mutation StarRepo(\$id: ID!) { \
addStar(input: {starrableId: \$id}) { \
starrable { \
... on Repository { name } \
viewerHasStarred
stargazers { totalCount }}}}}\",
\"variables\": \
{\"id\": \"MDEwOlJlcG9zaXRvcnkxMDg4OTA0MA==\"}}" \
https://api.github.com/graphql
mutation StarRepo($id: ID!) {
addStar(input: {starrableId: $id}) {
starrable {
... on Repository { name }
viewerHasStarred
stargazers { totalCount }}}}
{ "data": {
"addStar": {
"starrable": {
"name": "bork",
"viewerHasStarred": true,
"stargazers": { "totalCount": 211 }}}}}
Here’s what’s going on:
-
The
addStar
mutation requires anstarrableId
value from aStarrable
— Gist or Repository. You can get this from theStarrable
via itsid
field. -
The
addStar
mutation returns an returns anaddStarPayload
object, which has astarrable
field. This is a Union Type, since both Repositories and Gists are starrable. In fact, they implement thestarrable
interface, which is essentially a set of common fields across the implemented types. OnStarrable
, these fields includestargazers
andviewerHasStarred
. -
Since I also wanted the Repository’s name (to show you what you’ll star if you copy & paste this query), I had to use an inline fragment to get a field not included in
Starrable
, even though bothRepository
andgist
havename
fields.
If the id
variable looks a bit funny, run it through a base-64 decoder. It’s common in GraphQL APIs to make IDs opaque in this manner, such that they can represent any complex data the server needs for referencing particular things while discouraging the client from worrying about the particulars.
The last thing we should look at is error handling. Because queries are often asking for more than one thing at a time, GraphQL’s philosophy is to isolate the errors and return as much data as possible. I couldn’t replicate this behavior predictibly with GitHub’s API — queries that required pagination info, for example, did not return any data whatsoever — so instead here’s an example with an easy fix:
errors
POST /graphql HTTP/1.1
Authorization: bearer $TOKEN
Content-Type: application/json; charset=utf-8
Host: api.github.com
{"query":"query UserInfo($user: ID!) {
user(login: $user) {
login name bio company location websiteUrl createdAt
repositories { totalCount }
viewerCanFollow viewerIsFollowing }}",
"variables": {"user": "mattly"}}
curl -H "Authorization: bearer $TOKEN" -X POST -d "\
{ \"query\": \
\"query UserInfo(\$user: ID!) { \
user(login: \$user) { \
login name bio company location websiteUrl createdAt \
repositories { totalCount } \
viewerCanFollow viewerIsFollowing }}\", \
\"variables\": {\"user\": \"mattly\"}}" \
https://api.github.com/graphql
query UserInfo($user: ID!) {
user(login: $user) {
login name bio company location websiteUrl createdAt
repositories { totalCount }
viewerCanFollow viewerIsFollowing }}
{ "data": null,
"errors": [{
"message":
"Type mismatch on variable $user and argument login (ID! / String!)",
"locations": [{
"line": 1,
"column": 41 }]}]}
This should cover enough of the basics to get you going. I’d spend some time playing around with GitHub’s GraphQL Explorer to get a feel for how expressive GraphQL queries can be. Look at the introspected documentation, and write your own queries. Here’s an example query that will look at who you’re following, how many followers they have, what languages they use in their featured repositories, as well as who’s following you, whether you’re following them, what languages are used in their pinned repositories, and how many people they’re following. It could be the base for a little personal dashboard, and it’s just a single, concise query.
query {
viewer {
following(first: 100) {
nodes {
login
pinnedRepositories(first: 10) {
nodes { name languages(first: 10) { nodes { name }}}}
followers { totalCount }}}
followers(first: 100) {
nodes {
login
viewerIsFollowing
pinnedRepositories(first: 10) {
nodes { name languages(first: 10) { nodes { name }}}}
repositories { totalCount }
following { totalCount }}}}}
If you’re seriously considering using GraphQL in your client application — and I do recommend it — I’d suggest checking out a consumer library such as Apollo or Relay if you’re using JavaScript. These solve problems not common to all GraphQL APIs or use cases, can be prescriptive about how you deal with data in your app, and certainly involve more overhead and ceremony than simply using plain HTTP.