GraphQL body in Postman - Deep Dive

Overview - GraphQL body

What is it?

A GraphQL body is the part of a request that contains the query or mutation you want to send to a GraphQL server. It is usually written in JSON format and includes the query string and optional variables. This body tells the server exactly what data you want or what action you want to perform.

Why it matters

Without a properly structured GraphQL body, the server cannot understand what data you need or what operation to perform. This would make it impossible to get precise data or update information efficiently. The GraphQL body solves the problem of over-fetching or under-fetching data by letting clients specify exactly what they want.

Where it fits

Before learning about the GraphQL body, you should understand basic HTTP requests and JSON format. After mastering the GraphQL body, you can learn about GraphQL schemas, queries, mutations, and how to test GraphQL APIs effectively using tools like Postman.

Mental Model

Core Idea

The GraphQL body is a precise instruction set in JSON that tells the server exactly what data to fetch or what action to perform.

Think of it like...

It's like ordering food at a restaurant by specifying exactly what you want on your plate instead of just saying 'I want food'.

┌─────────────────────────────┐
│        GraphQL Body         │
├─────────────┬───────────────┤
│   query     │  String with  │
│             │  requested    │
│             │  fields       │
├─────────────┼───────────────┤
│  variables  │  JSON object  │
│             │  with values  │
└─────────────┴───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding GraphQL Requests

Concept: GraphQL requests use a body to send queries or mutations to the server.

A GraphQL request is sent over HTTP, usually as a POST request. The body of this request contains a JSON object with at least a 'query' field. This 'query' field is a string that describes what data you want or what operation you want to perform.

Result

You can send a request to the server that asks for specific data or performs an action.

Knowing that GraphQL uses a JSON body to specify requests helps you understand how to communicate precisely with the server.

2

Foundation

Basic Structure of GraphQL Body

Concept: The GraphQL body has a simple JSON structure with 'query' and optional 'variables'.

The minimal GraphQL body looks like this: { "query": "{ user { id name } }" }. This asks for the 'id' and 'name' of a user. Variables can be added as a separate JSON object to make queries dynamic.

Result

You can write simple queries inside the body and send them to get data.

Understanding the JSON format of the body is key to writing valid GraphQL requests.

3

Intermediate

Using Variables in GraphQL Body

🤔Before reading on: Do you think variables in GraphQL body replace parts of the query string or add extra data? Commit to your answer.

Concept: Variables allow you to write flexible queries by separating query structure from data values.

Instead of hardcoding values in the query, you define variables in the query string and provide their values in the 'variables' JSON object. For example: { "query": "query getUser($id: ID!) { user(id: $id) { name } }", "variables": { "id": "123" } }.

Result

You can reuse queries with different inputs without changing the query string itself.

Knowing how variables work prevents rewriting queries and helps test multiple cases efficiently.

4

Intermediate

Handling Mutations in GraphQL Body

🤔Before reading on: Do you think mutations use a different body format than queries? Commit to your answer.

Concept: Mutations are operations that change data and use the same GraphQL body format as queries but with a 'mutation' keyword.

To perform a mutation, you write it inside the 'query' field with the 'mutation' keyword. For example: { "query": "mutation { addUser(name: \"Alice\") { id name } }" }. Variables can also be used here.

Result

You can send requests that modify data on the server using the same body structure.

Understanding that mutations share the same body format simplifies learning and testing GraphQL operations.

5

Advanced

Best Practices for GraphQL Body in Postman

🤔Before reading on: Should GraphQL bodies always be sent as raw JSON or can other formats work? Commit to your answer.

Concept: Postman requires the GraphQL body to be sent as raw JSON with correct headers and formatting for successful requests.

In Postman, set the request method to POST, select 'raw' body type, and choose 'JSON' format. The body must be a valid JSON string with 'query' and optional 'variables'. Also, set the 'Content-Type' header to 'application/json'.

Result

Your GraphQL requests will be accepted and processed correctly by the server.

Knowing how to format and send the body in Postman avoids common errors and speeds up testing.

6

Expert

Advanced GraphQL Body Features and Pitfalls

🤔Before reading on: Can you include multiple operations in one GraphQL body and control which runs? Commit to your answer.

Concept: GraphQL bodies can include multiple named operations, and you can specify which one to execute using the 'operationName' field.

You can send a body like { "query": "query A { user { id } } query B { post { id } }", "operationName": "B" }. This runs only operation B. Also, deeply nested queries and fragments can be included in the body. Mistakes like invalid JSON or missing variables cause errors.

Result

You can run complex tests and avoid common errors by mastering these features.

Understanding these advanced features helps you write flexible, maintainable tests and debug tricky issues.

Under the Hood

When a GraphQL request is sent, the server reads the JSON body, parses the 'query' string, and validates it against the schema. Variables are injected into the query before execution. The server then resolves the requested fields and returns a JSON response with exactly the requested data or errors.

Why designed this way?

GraphQL was designed to let clients specify exactly what data they want in a single request, avoiding multiple endpoints and over-fetching. Using a JSON body with a query string and variables separates the query logic from data, making requests flexible and efficient.

┌───────────────┐
│ HTTP Request  │
│ (POST + JSON) │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Parse JSON    │
│ Extract Query │
│ & Variables   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Validate &    │
│ Execute Query │
│ with Variables│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Return JSON   │
│ Response      │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think the GraphQL body can be sent as plain text without JSON formatting? Commit to yes or no.

Common Belief: Some believe you can send the GraphQL query as plain text in the body without JSON formatting.

Reality: GraphQL requests require the body to be a valid JSON object with at least a 'query' field as a string.

Why it matters: Sending plain text causes the server to reject the request or return errors, blocking testing or data fetching.

Quick: Do you think variables in the GraphQL body are optional even if the query uses them? Commit to yes or no.

Common Belief: Many think variables are optional even when the query defines them as required.

Reality: If the query declares variables as required (with !), you must provide them in the 'variables' object or the server will error.

Why it matters: Missing required variables causes failed requests and confusion during testing.

Quick: Can you include multiple queries in one GraphQL body and have them all run automatically? Commit to yes or no.

Common Belief: Some believe that if multiple queries are in the body, the server runs all of them by default.

Reality: Only one operation runs per request; if multiple are present, you must specify which one with 'operationName'.

Why it matters: Not specifying 'operationName' leads to errors or unexpected behavior, complicating test results.

Quick: Do you think mutations require a different content type or body format than queries? Commit to yes or no.

Common Belief: Some think mutations need a special content type or body format different from queries.

Reality: Mutations use the exact same JSON body format as queries, just with the 'mutation' keyword in the query string.

Why it matters: Misunderstanding this causes unnecessary complexity and errors in test setup.

Expert Zone

1

GraphQL bodies can include fragments to reuse parts of queries, reducing duplication and improving maintainability.

2

The 'operationName' field is essential when sending multiple operations in one body to avoid ambiguity and errors.

3

Variables in the body must match the types declared in the query exactly; mismatches cause subtle runtime errors.

When NOT to use

GraphQL bodies are not suitable for simple REST APIs or when the server does not support GraphQL. In such cases, use standard REST request bodies or other API formats like SOAP or gRPC.

Production Patterns

In production, GraphQL bodies are often generated dynamically by clients or testing tools. They use variables extensively for flexibility. Testing frameworks automate sending bodies with different variables to cover edge cases and validate schema changes.

Connections

JSON

GraphQL body is formatted as JSON

Understanding JSON structure and syntax is essential to correctly write and parse GraphQL bodies.

HTTP POST Requests

GraphQL bodies are sent inside HTTP POST requests

Knowing how HTTP POST works helps in setting headers and body correctly for GraphQL communication.

SQL Query Language

GraphQL queries specify data retrieval like SQL but with a different syntax and flexibility

Comparing GraphQL queries to SQL helps understand how clients specify exactly what data they want, avoiding over-fetching.

Common Pitfalls

#1 Sending GraphQL query as plain text without JSON formatting

Wrong approach:

{ user { id name } }

Correct approach:

{ "query": "{ user { id name } }" }

Root cause:

Misunderstanding that GraphQL requests require a JSON object body, not raw query text.

#2 Omitting required variables in the 'variables' object

Wrong approach:

{ "query": "query getUser($id: ID!) { user(id: $id) { name } }" }

Correct approach:

{ "query": "query getUser($id: ID!) { user(id: $id) { name } }", "variables": { "id": "123" } }

Root cause:

Not realizing that required variables must be provided separately in the variables JSON.

#3 Not setting Content-Type header to application/json

Wrong approach:

POST request with GraphQL body but missing or wrong Content-Type header

Correct approach:

POST request with header 'Content-Type: application/json' and proper JSON body

Root cause:

Ignoring HTTP header requirements causes server to misinterpret the request body.

Key Takeaways

A GraphQL body is a JSON object that contains a query string and optional variables to specify exactly what data or action is requested.

Variables in the body allow dynamic and reusable queries, separating data from query structure.

Mutations use the same body format as queries but perform data changes on the server.

Proper formatting and headers are essential when sending GraphQL bodies, especially in tools like Postman.

Advanced features like multiple operations and fragments in the body enable flexible and maintainable API interactions.