michaelschiemer/docs/graphql-examples.md

GraphQL Examples

This framework includes a basic GraphQL implementation with Query and Mutation support.

GraphQL Endpoints

• POST /graphql - GraphQL endpoint for queries and mutations
• GET /graphql - GraphQL Playground (interactive editor)
• GET /graphql/schema - View schema definition

Schema Definition

The current schema includes:

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  active: Boolean!
  created_at: String!
}

input UserInput {
  name: String!
  email: String!
  age: Int
  active: Boolean
}

type UserStats {
  total: Int!
  active: Int!
  inactive: Int!
  average_age: Float!
}

type Query {
  users(active: Boolean, limit: Int): [User!]!
  user(id: ID!): User
  userStats: UserStats!
}

type Mutation {
  createUser(input: UserInput!): User!
  updateUser(id: ID!, input: UserInput!): User
  deleteUser(id: ID!): Boolean!
}

Query Examples

Get All Users

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { users { id name email active } }"
  }'

Response:

{
  "data": {
    "users": [
      {
        "id": "1",
        "name": "John Doe",
        "email": "john@example.com",
        "active": true
      },
      {
        "id": "2",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "active": true
      },
      {
        "id": "3",
        "name": "Bob Wilson",
        "email": "bob@example.com",
        "active": false
      }
    ]
  }
}

Get Active Users Only

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { users(active: true) { id name email } }"
  }'

Get Limited Number of Users

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { users(limit: 2) { id name email } }"
  }'

Get Single User by ID

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { user(id: \"1\") { id name email age active created_at } }"
  }'

Response:

{
  "data": {
    "user": {
      "id": "1",
      "name": "John Doe",
      "email": "john@example.com",
      "age": 30,
      "active": true,
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}

Get User Statistics

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { userStats { total active inactive average_age } }"
  }'

Response:

{
  "data": {
    "userStats": {
      "total": 3,
      "active": 2,
      "inactive": 1,
      "average_age": 30.0
    }
  }
}

Mutation Examples

Create New User

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "mutation { createUser(input: { name: \"Alice Johnson\", email: \"alice@example.com\", age: 28, active: true }) { id name email age active created_at } }"
  }'

Response:

{
  "data": {
    "createUser": {
      "id": "4",
      "name": "Alice Johnson",
      "email": "alice@example.com",
      "age": 28,
      "active": true,
      "created_at": "2024-08-08T10:30:00Z"
    }
  }
}

Update Existing User

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "mutation { updateUser(id: \"1\", input: { name: \"John Smith\", age: 31 }) { id name email age } }"
  }'

Response:

{
  "data": {
    "updateUser": {
      "id": "1",
      "name": "John Smith",
      "email": "john@example.com",
      "age": 31
    }
  }
}

Delete User

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "mutation { deleteUser(id: \"3\") }"
  }'

Response:

{
  "data": {
    "deleteUser": true
  }
}

Using Variables

Query with Variables

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query GetUser($userId: ID!) { user(id: $userId) { id name email } }",
    "variables": { "userId": "1" }
  }'

Mutation with Variables

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "mutation CreateUser($input: UserInput!) { createUser(input: $input) { id name email } }",
    "variables": {
      "input": {
        "name": "Charlie Brown",
        "email": "charlie@example.com",
        "age": 22,
        "active": true
      }
    }
  }'

Complex Queries

Multiple Queries in One Request

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { users(active: true) { id name email } userStats { total active } }"
  }'

Response:

{
  "data": {
    "users": [
      {
        "id": "1",
        "name": "John Doe",
        "email": "john@example.com"
      },
      {
        "id": "2",
        "name": "Jane Smith",
        "email": "jane@example.com"
      }
    ],
    "userStats": {
      "total": 3,
      "active": 2
    }
  }
}

Using Aliases

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { activeUsers: users(active: true) { id name } inactiveUsers: users(active: false) { id name } }"
  }'

Error Handling

Invalid Query

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { nonexistentField }"
  }'

Response:

{
  "errors": [
    {
      "message": "Query field 'nonexistentField' not found",
      "extensions": {
        "code": "VAL_BUSINESS_RULE_VIOLATION"
      }
    }
  ]
}

User Not Found

curl -X POST https://localhost/graphql \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" \
  -d '{
    "query": "query { user(id: \"999\") { id name } }"
  }'

Response:

{
  "data": {
    "user": null
  }
}

GraphQL Playground

Visit https://localhost/graphql in your browser to access the interactive GraphQL Playground:

• Query Editor: Write and test GraphQL queries
• Variables Panel: Define query variables
• Results Panel: View query results
• Schema Explorer: Browse available types and fields
• Execute Button: Run queries with Ctrl+Enter

Best Practices

1. Use Field Selection: Only request fields you need
2. Use Variables: For dynamic queries and better caching
3. Handle Errors: Always check for errors in responses
4. Batch Operations: Combine multiple queries when possible
5. Type Safety: Use proper types in mutations
6. Validation: Validate input data before mutations
7. Caching: Consider caching strategies for queries