Skip to content

GraphQL

A while back, I did a self-led "30 days of GraphQL" and it turned out to be super useful. I find myself chatting with folks about GraphQL in pairing sessions. It's useful for troubleshooting and for better understanding how GitLab works. In this file, I am drafting a GraphQL training module aimed at GitLab Support Engineers with little to no experience with GraphQL.

Stage 0: Create and commit to the module

  1. Create an issue using this template by making the Issue Title: GraphQL - "your name"
  2. Add yourself and your trainer (if you have one) as the assignees. Feel free to ping the maintainer(s) of this training module to see if they can help you with this module.
    1. Consider setting up a pairing session to spend some time using GraphQL together.
  3. Notify your manager to let them know you've started.
  4. Consider setting up a self-managed GitLab instance in GitLab Sandbox Cloud with an Ultimate license in order to follow along with all of the demos. (It's not necessary: if you see the 🖥️ emoji, that step requires a test instance.)
  5. Optional: Set a milestone, if applicable, and a due date to help motivate yourself!

Stage 1: What is GraphQL?

In this stage, we get a high-level understanding of what GraphQL is, why anyone would use it and some of the basic terms to be familiar with.

  • What even is GraphQL?
    • It's an alternative to REST.
    • With GraphQL queries, you describe the data that you want and the response returns only the data you need. In REST, you have to parse through the entire response on the client side.
    • You can read and change data via GraphQL.
    • ELI5: graphql
    • Read About GraphQL
    • Read GraphQL: A data query language
      • This 2015 post from Meta (then Facebook) is super short and describes some of the challenges that they solved with GraphQL. Understanding why Meta built GraphQL provides helpful context on why it's so broadly adopted today, more than ten years after it was first built.
      • GraphQL was made public in 2015.
      • Optional Read What is GraphQL? Part 1: The Facebook Years
  • Why would anyone use it?

The Basics of GraphQL

These are some basic GraphQL terms to be familiar with:

  • queries
    • This is how you retrieve data. Think of a GET request when using a REST API.
  • mutations
    • This is how you can change things. Think of a POST request when using a REST API.
  • resolvers
    • This is how the data for your queries is retrieved. In GitLab, these will be functions in the GitLab source code.
  • authentication
    • typically very common to authentication with REST APIs

REST vs GraphQL in GitLab

  • Take a look at these examples of GraphQL usage in the GitLab source code
  • Run through the demo below to see the difference between REST and GraphQL APIs.

Here's a quick demo to illustrate how GraphQL can be so helpful: let's say we want to get a user's name and nothing else!

  1. When you are already logged in to gitlab.com, go to https://gitlab.com/api/v4/user.
  2. Observe that the name is there but there is a lot of extra information that we don't really want
  3. Head over to the GraphQL explorer
  4. Issue this query: {currentUser {name}}
  5. Observe that the name is returned with none of the extra information we saw before

Stage 2: Hands on with GraphQL and GitLab

  • Read about Global IDs to understand how to reference things like users (gid://gitlab/User/0123456789), projects(gid://gitlab/Project/000000), snippets () and more!
    • You might retrieve the project ID via logs, the Web interface or a screenshot.

We'll cover different ways to issue GraphQL queries and mutations:

  • "API clients" like cURL, Insomnia, Postman
  • GraphiQL -- recommended way to get started
    • Observe the auto-complete! You don't need to read through the entire reference.
  • In Rails Console!: https://docs.gitlab.com/ee/api/graphql/getting_started.html#rails-console
  • GraphQL is baked into GitLab in interesting places:
    • link to examples with FE queries
    • When we're iterating, an early feature may only be available via the GraphQL API to start, as with audit event streaming.
  • Consider joining the #graphql and #f_graphql Slack channels.

Examples (with emoji!)

Stage 3: GraphQL for Troubleshooting

GraphQL can be super helpful for troubleshooting all kinds of things in GitLab!

  • Maybe you want to write snippets for the GitLab Rails Console but writing Ruby is not your strength: you can send GraphQL queries and mutations via the GitLab Rails Console.

  • Maybe the REST API is not working as expected and you'd like to see if the corresponding query or mutation is working via the GraphQL API:

    • If yes: you have a workaround!
    • If no: you have helped to clarify the problem statement and to start to isolate the cause of the problem

  • Getting errors

  • Understanding how GraphQL responds
    • You might see null. The problem could be the token. GraphQL tends not to be super verbose about this.
  • Using GraphQL mutations to change things in GitLab

Here's an example mutation showing how to assign a security policy project:

mutation {
  securityPolicyProjectAssign(
    input: {fullPath: "bcarranza/detecting-secrets", securityPolicyProjectId: "gid://gitlab/Project/000000"}
  ) {
    clientMutationId
    errors
  }
}

GraphQL Tools

Stage 4: Building Better Queries

There are a lot of really cool things you can do with GraphQL. So far, we have just built some pretty simple queries. Let's do a bit more!

  • Use the GraphQL reference and the auto-complete support in GraphQL Explorer to build a query for some data that interests you.
    • Watch this recording for an example of how to build a GraphQL query in this way.

Stage 5: Beyond!

This is optional but if you're finding this all super fun and interesting, here's more! Try one, try a few or do them all!

Penultimate stage: Review

Any updates or improvements needed? If there are any dead links, out of date or inaccurate content, missing content whether in this module or in other documentation, list it below as tasks for yourself! Once ready, have a maintainer or manager review.

  1. Update ...

Final stage: Completion

  1. Have your trainer review your tickets and assessment. If you do not have a trainer, ask an expert to review.
  2. Manager: schedule a call (or integrate into 1:1) to review how the module went.
  3. Submit a MR to update modules and knowledge_areas in the Support Team yaml file with this training module's topic. You will now be listed as an expert in GraphQL on the GitLab Support Team Skills by Person page.