Playing with Github’s graphql

Ayush Goel
Jul 30, 2017 · 2 min read

Graphql is a query language (duh). Instead of going via the REST APIs given by Github, I instead tried this. There is very less documentation on it, so I will give a basic primer on it.

https://developer.github.com/v4/ this is the official page for the new API.

My motivation was to query and find
1. recent tags
2. recent releases
of a github repository. This so that I can notify my team when someone creates a tag on our repo but forgets to add release notes for it. FWIW, if you don’t draft a release, you don’t create release notes and a month later, no one knows what the version tag is for.

The bot’s message on Flock (check https://github.com/ayushgoel/LongShot)

GraphQL is very interesting with the highlight being the self-introspection feature. You can get the schema with the graph query itself. Check https://developer.github.com/v4/guides/intro-to-graphql/#discovering-the-graphql-api

The Schema has
1. Node — these are the actual data structures you want to care about. Think classes.
2. Edge — edge is a connection between two nodes. Relevant when creating query.
3. Interfaces — A protocol that a node can implement. Helpful in explorer.
4. Scalar — A node’s attribute that your query can ask for.

GraphQL is designed to return you only the values you want instead of everything (like what happened in REST APIs). So, your query should define every and all scalars it is interested in.

That’s it. These are the only notes you may need. You can be smart and start using variables, but I don’t think that’s too necessary. Move fast, break things, maybe. :)

The finalised code: https://github.com/ayushgoel/LongShot


Example:

curl -X POST \
https://api.github.com/graphql \
-H 'authorization: token <token>' \
-H 'content-type: application/json' \
-d '{"query": "query($repository: String!) {repository(owner: \"<owner>\",name: $repository) {refs(last: 10,refPrefix:\"refs/tags/\") {edges {node{name}}}}}",
"variables": "{\"repository\": \"<repo-name>\"}"
}'
  1. Use POST request
  2. Your query and variables are two different keys in the POST data’s JSON: {"query": <query string>, "variables": <variable JSON>}
Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade