Skip to main content

GraphQL Guide

GraphQL is a query language and runtime for APIs that provides a complete and understandable description of the data in your API. It gives clients the power to ask for exactly what they need and nothing more.

What is GraphQL?​

GraphQL is a specification for APIs that was developed by Facebook in 2015. Unlike REST APIs where you have multiple endpoints returning fixed data structures, GraphQL has a single endpoint that can return any data structure you request.

Strongly Typed​

GraphQL is strongly typed, meaning every piece of data has a specific type defined in the schema. This provides several benefits:

  • Type Safety: Compile-time validation prevents runtime errors
  • Self-Documenting: The schema serves as documentation
  • IDE Support: Better autocomplete and IntelliSense
  • Validation: Queries are validated against the schema before execution

For example, if you try to query a field that doesn't exist or pass the wrong type for a variable, GraphQL will return a clear error message rather than unexpected behavior.

Key Concepts​

  • Schema: Defines the types and relationships in your data
  • Queries: Read operations to fetch data
  • Mutations: Write operations to modify data
  • Subscriptions: Real-time updates (not currently supported in our API)
  • Resolvers: Functions that determine how to fetch the types defined in your schema

How GraphQL Works​

Queries​

Queries are used to fetch data. You specify exactly what fields you want to retrieve:

query GetProjects {
  projects {
    data {
      id
      name
      code
      address
      city
      zipCode
      startDate
      endDate
    }
    paginationInfo {
      totalCount
      currentPageNumber
      pageSize
    }
  }
}

Mutations​

Mutations are used to modify data (create, update, delete):

mutation CreateProject($project: CreateProjectInput!) {
  createProject(project: $project) {
    id
    name
    code
    address
    city
    zipCode
    startDate
    endDate
  }
}

Variables​

GraphQL supports variables to make queries dynamic:

query GetProject($id: UUID!) {
  project(id: $id) {
    id
    name
    code
    address
    city
    zipCode
    startDate
    endDate
    country {
      name
      iso
    }
  }
}

With variables:

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

External GraphQL Resources​

To learn more about GraphQL, we recommend these resources:

GraphQL Playground​

We provide an interactive GraphQL playground where you can explore our API schema and test queries in real-time.

Access the Playground​

Visit our GraphQL Playground to start exploring the API.

How It Works​

The playground provides:

  • Schema Explorer: Browse all available types, queries, and mutations
  • Query Editor: Write and execute GraphQL queries
  • Variables Panel: Set variables for your queries
  • Results Panel: View query results in real-time
  • Documentation: Inline documentation for all fields and types

Why It's Useful​

The playground is perfect for:

  • Learning the API structure
  • Testing queries before implementing them in code
  • Debugging API issues
  • Exploring available data and operations
  • Sharing queries with team members
Pro Tip

Press Ctrl+Space in the query editor to see intelligent suggestions and auto-completion for fields, types, and operations!

GraphQL Clients​

JavaScript/TypeScript​

Apollo Client - Most popular GraphQL client for React

npm install @apollo/client graphql

📖 Apollo Client Documentation

Urql - Lightweight and flexible GraphQL client

npm install urql graphql

📖 Urql Documentation

GraphQL Request - Minimal GraphQL client

npm install graphql-request graphql

📖 GraphQL Request Documentation

Python​

GQL - Modern GraphQL client for Python

pip install gql[requests]

📖 GQL Documentation

Python GraphQL Client - Simple GraphQL client

pip install python-graphql-client

📖 Python GraphQL Client Documentation

Java​

GraphQL Java - Java implementation of GraphQL

<dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphql-java</artifactId>
    <version>21.0</version>
</dependency>

📖 GraphQL Java Documentation

.NET​

GraphQL.Client - GraphQL client for .NET

dotnet add package GraphQL.Client

📖 GraphQL.Client Documentation

Go​

Machinebox GraphQL - GraphQL client for Go

go get github.com/machinebox/graphql

📖 Machinebox GraphQL Documentation

Using cURL​

You can also interact with our GraphQL API using cURL:

Basic Query​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"query": "query { projects { data { id name code } paginationInfo { totalCount } } }"}' \
  https://api.letsbuild.com/v1/graphql

Query with Variables​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "query": "query GetProject($id: UUID!) { project(id: $id) { id name code address city zipCode } }",
    "variables": {"id": "123e4567-e89b-12d3-a456-426614174000"}
  }' \
  https://api.letsbuild.com/v1/graphql

Mutation​

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "query": "mutation CreateProject($project: CreateProjectInput!) { createProject(project: $project) { id name code } }",
    "variables": {
      "project": {
        "name": "My New Project",
        "code": "PROJ001",
        "startDate": "2024-01-01"
      }
    }
  }' \
  https://api.letsbuild.com/v1/graphql

Pretty Print Results​

Add jq to format the JSON response:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"query": "query { projects { data { id name code } paginationInfo { totalCount } } }"}' \
  https://api.letsbuild.com/v1/graphql | jq '.'

Best Practices​

  1. Request Only What You Need: GraphQL's power comes from requesting exactly the fields you need
  2. Use Variables: Always use variables for dynamic values to prevent injection attacks
  3. Handle Errors: GraphQL returns errors in a structured format - always handle them
  4. Use Fragments: Reuse common field selections with fragments
  5. Optimize Queries: Avoid deeply nested queries that might cause performance issues

Next Steps​

Now that you understand GraphQL basics: