GraphQL represents a giant leap forward in the world of APIs - From REST to GraphQL

"As a significant departure from the REST API, GraphQL requires some not-so-subtle shifts in the way we think about consuming and altering data."  - Mark,Matt Platform engineers GitHub

Issues with REST:

• REST APIs are designed to interact with one specific end point at a time. For example, you can get a list of all your issues on GitHub, but you can’t get a list of issues and the comments on those issues at the same time. This means you often need to make more than one “request” to the API to get the exact information you need.

• REST API results are determined by the API developer, and they want to make sure you have everything you could possibly want. This often means you are getting way more information than you intend to use.

GraphQL is a more flexible query structure, which allows you to request information based on connections across traditional data points.

Running Your First GraphQL Query

1. Navigate to the GraphQL explorer.
2. Once the page has loaded, click the “Sign in with GitHub” button. If you don’t have a GitHub account, here are some instructions for getting an account setup.
   On your first log in, The GraphQL interface displays a sample query in the left pane that should look like this:

   # Type queries into this side of the screen, and you will
   # see intelligent typeaheads aware of the current GraphQL type schema,
   # live syntax, and validation errors highlighted within the text.
   
   # We'll get you started with a simple query showing your username!
   query {
     viewer {
       login
     }
   }
   

3. Click the “Execute Query” button (it looks like a Play button) to run the query that is in the left pane and display the results in the right pane.
   Clicking “Execute Query” should present something that looks like this:

   {
     "data": {
       "viewer": {
         "login": "githubteacher"
       }
     }
   }
   

   The response from a query in GraphQL will be JSON, just like the query itself, and is returned in the exact same format as the request.
4. Make changes to the sample query.
   In this case, we only asked GraphQL to tell us our login name, but what if we wanted to know more?
   Just below login, add a new line with the text avatarURL. Now your query should look like this:

    {
      viewer {
        login
        avatarUrl
      }
    }

Components of our query

• viewer: Who is currently the logged in user? (you!)
• contributedRepositories(last:#, privacy:PUBLIC): Contributed repositories is what is known as a connection. It a relationship between two sets of data. In this case, it is a connection between the user (in this case the logged in user) and the (most recent) repositories the viewer has contributed to. We are providing two arguments to help us limit the results.
  • Last: tells the query to return the most recent results. In this case, the # must be used to limit the number of repositories returned.
  • We also chose to only display PUBLIC repositories by providing the privacy argument. We could also set this parameter to PRIVATE, or leave it out altogether if we’d like PUBLIC and PRIVATE repositories.
• edge: It is easiest to think of an edge as a bridge between two sets of data. You will need an edge any time you are working between nodes.
• node: A node is a set of data. If an edge is a bridge connecting two islands, the node is the island. Within a node, you can select specific data you would like to view. In this case, the node contains the information about the repositories.

  For a visual example of nodes and edges, view the GraphQL Voyager site. Any column of data in the graphs would be considered a node, and the lines connecting them would be considered edges.

• owner: Within the node, you will find specific pieces of information called interfaces. These are interfaces have additional layers of data.
• login: The repository owner’s username on GitHub. The owner may be an individual, or an organization.
• name: The name of the repository.
• url: The repository’s URL.

More here: https://services.github.com/on-demand/graphql/mutation