Using JSON with GraphQL APIs

GraphQL is a powerful query language for APIs that provides flexibility and efficiency in data fetching. At its core, GraphQL APIs heavily rely on JSON as the medium of request and response data.

In this blog, we’ll explore how JSON is used in GraphQL APIs, understand the request-response cycle, and review practical examples and patterns commonly seen in modern development.

📘 Table of Contents

1. Introduction to GraphQL and JSON
2. Anatomy of a GraphQL Request
3. JSON in GraphQL Queries
4. JSON in GraphQL Responses
5. GraphQL Variables with JSON
6. Real-World Example: User Profile
7. Error Handling and JSON
8. Integrating GraphQL with REST and JSON APIs
9. JSON Best Practices with GraphQL
10. Tools for Working with GraphQL and JSON

🔍 Introduction to GraphQL and JSON

• GraphQL is a query language for APIs developed by Facebook. It allows clients to request specific fields and nested data in a single query.
• JSON (JavaScript Object Notation) is the format used by GraphQL for both requests and responses.

GraphQL and JSON together provide a streamlined, predictable, and developer-friendly API experience.

✍️ Anatomy of a GraphQL Request

GraphQL queries are typically sent as HTTP POST requests with a JSON payload. The request body contains:

• query: The GraphQL query string
• variables: (Optional) A map of dynamic values
• operationName: (Optional) If multiple operations are included

Example: Basic Request

{
  "query": "query { user(id: \"1\") { name email } }"
}

Example: With Variables

{
  "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
  "variables": {
    "id": "1"
  }
}

📤 JSON in GraphQL Queries

While GraphQL queries use their own syntax, they are embedded as strings inside a JSON object when making API calls.

Example Query

{
  "query": "{ books { title author { name } } }"
}

Embedded GraphQL

{
  books {
    title
    author {
      name
    }
  }
}

📥 JSON in GraphQL Responses

GraphQL servers always respond with JSON-formatted data. The main keys in the response are:

• data: Contains the requested fields
• errors: (Optional) An array of errors, if any

Example Response

{
  "data": {
    "books": [
      {
        "title": "Sapiens",
        "author": {
          "name": "Yuval Noah Harari"
        }
      },
      {
        "title": "The Alchemist",
        "author": {
          "name": "Paulo Coelho"
        }
      }
    ]
  }
}

🧩 GraphQL Variables with JSON

GraphQL supports variables to make queries more reusable. These variables are passed as a JSON object in the request.

Query with Variables

query GetBook($bookId: ID!) {
  book(id: $bookId) {
    title
    author {
      name
    }
  }
}

JSON Request Body

{
  "query": "query GetBook($bookId: ID!) { book(id: $bookId) { title author { name } } }",
  "variables": {
    "bookId": "101"
  }
}

💼 Real-World Example: User Profile

GraphQL Query

query {
  user(id: "123") {
    name
    email
    posts {
      title
      published
    }
  }
}

JSON Request

{
  "query": "{ user(id: \"123\") { name email posts { title published } } }"
}

JSON Response

{
  "data": {
    "user": {
      "name": "Praveen Patel",
      "email": "praveen@example.com",
      "posts": [
        {
          "title": "Understanding JSONPath",
          "published": true
        },
        {
          "title": "Intro to GraphQL",
          "published": false
        }
      ]
    }
  }
}

❗ Error Handling and JSON

When a query fails or has partial results, the server returns an errors array.

Example Error Response

{
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"]
    }
  ],
  "data": {
    "user": null
  }
}

🔄 Integrating GraphQL with REST and JSON APIs

GraphQL servers often act as aggregators that call internal or third-party REST APIs (which also use JSON).

Example Scenario

1. GraphQL server receives a query.
2. It fetches data from one or more REST APIs (returning JSON).
3. The final result is merged and returned as a single JSON response to the client.

This allows frontends to avoid multiple REST calls and simplifies client logic.

✅ JSON Best Practices with GraphQL

• Always validate your input variables (they're just JSON).
• Use camelCase consistently in field names for compatibility with JS clients.
• Limit nested depth in queries to avoid large, unreadable JSON responses.
• Leverage null values in JSON to handle optional or missing fields.

🛠️ Tools for Working with GraphQL and JSON

• GraphQL Playground / GraphiQL – IDEs to write and test GraphQL queries.
• Postman – Supports GraphQL queries with full JSON payloads.
• Apollo Client – JS library for managing GraphQL queries.
• JSONLint – Validates your JSON syntax.
• JQ – Command-line JSON processor for working with responses.

🎯 Conclusion

Understanding how GraphQL and JSON work together is essential for modern API development. JSON provides the structure, while GraphQL gives clients precise control over data retrieval. Whether you're building APIs or consuming them, mastering this interaction will make your development workflow faster, more predictable, and easier to maintain.