What is GraphQL?

GraphQL is a powerful, open-source query language for APIs and a server-side runtime for executing those queries. It gives clients the power to ask for exactly the data they need often in a single request. This offers a more flexible and efficient alternative to traditional REST APIs, particularly for complex and data-driven applications.

How GraphQL works

GraphQL uses a strongly typed schema to define an API's capabilities and data structure.

Schema definition: The server-side developer creates a schema using the GraphQL Schema Definition Language (SDL). This schema describes all the possible data and the relationships between data types (e.g., User has many Notes).

Client query: The client application, such as an API client script or external integration, sends a query to a GraphQL API endpoint. In the query, the client specifies the type of data they want with it's exact fields, relationships to other types of data and their exact fields.

Execution and resolution: The GraphQL server validates the query against the schema. It then resolves this down to the matching data for all the objects with the specified fields, relationships, and nested data.

Predicted response: The server returns a JSON object containing only the requested data, matching the structure of the original query.

API Endpoints

The endpoint for sending GraphQL queries to is a POST request to/v1/graphql and accepts a query body parameter containing the GraphQL query.

Exploring the Schema

You can explore the schema using a GraphQL client such as Insomnia, or Postman. These tools will allow you to write GraphQL queries with autocomplete, as well as showing auto-generated documentation for the GraphQL types in your API.

Examples

Basic Query

Here's an example GraphQL query that fetches research and returns the ID and title of the note.

{
  research(
    first: 5
  ) {
    edges {
      node {
        id
        title
      }
    }
  }
}

The result of this query would look like this:

{
  "data": {
    "research": {
      "edges": [
        {
          "node": {
            "id": "68b993fb85d14160d40303fd",
            "title": "Follow up call"
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030407",
            "title": "Info Request - Klein-Kiehn"
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d403041b",
            "title": "Call with Klein-Kiehn"
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030431",
            "title": "Klein-Kiehn: 2025-01-06 expectations"
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030438",
            "title": "Klein-Kiehn - Distribution - 2025-02-06"
          }
        }
      ]
    }
  }
}

Query with Connections

This query makes connections to other data types and returns fields on them. In this example they are author, shared groups, and shared users.

{
  research(
    first: 5
  ) {
    edges {
      node {
        id
        title
        revision
        author {
          name          
        }
        sharedGroups {
          name
        }
        sharedUsers {
          name
        }
      }
    }
  }
}

The result of this query is:

{
  "data": {
    "research": {
      "edges": [
        {
          "node": {
            "id": "68b993fb85d14160d40303fd",
            "title": "Follow up call",
            "revision": 2,
            "author": {
              "name": "Julian Beer"
            },
            "sharedGroups": [
              {
                "name": "Everyone"
              }
            ],
            "sharedUsers": []
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030407",
            "title": "Info Request - Klein-Kiehn",
            "revision": 2,
            "author": {
              "name": "Dr. Santiago Bauch I"
            },
            "sharedGroups": [
              {
                "name": "Everyone"
              }
            ],
            "sharedUsers": []
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d403041b",
            "title": "Call with Klein-Kiehn",
            "revision": 2,
            "author": {
              "name": "Dr. Santiago Bauch I"
            },
            "sharedGroups": [],
            "sharedUsers": []
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030431",
            "title": "Klein-Kiehn: 2025-01-06 expectations",
            "revision": 2,
            "author": {
              "name": "Dr. Santiago Bauch I"
            },
            "sharedGroups": [
              {
                "name": "Everyone"
              }
            ],
            "sharedUsers": []
          }
        },
        {
          "node": {
            "id": "68b993fb85d14160d4030438",
            "title": "Klein-Kiehn - Distribution - 2025-02-06",
            "revision": 2,
            "author": {
              "name": "Julian Beer"
            },
            "sharedGroups": [
              {
                "name": "Everyone"
              }
            ],
            "sharedUsers": []
          }
        }
      ]
    }
  }
}