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:

```graphql
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

```bash
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:
```json
{
  "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

```bash
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

```bash
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

```bash
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:
```json
{
  "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

```bash
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:
```json
{
  "data": {
    "userStats": {
      "total": 3,
      "active": 2,
      "inactive": 1,
      "average_age": 30.0
    }
  }
}
```

## Mutation Examples

### Create New User

```bash
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:
```json
{
  "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

```bash
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:
```json
{
  "data": {
    "updateUser": {
      "id": "1",
      "name": "John Smith",
      "email": "john@example.com",
      "age": 31
    }
  }
}
```

### Delete User

```bash
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:
```json
{
  "data": {
    "deleteUser": true
  }
}
```

## Using Variables

### Query with Variables

```bash
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

```bash
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

```bash
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:
```json
{
  "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

```bash
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

```bash
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:
```json
{
  "errors": [
    {
      "message": "Query field 'nonexistentField' not found",
      "extensions": {
        "code": "VAL_BUSINESS_RULE_VIOLATION"
      }
    }
  ]
}
```

### User Not Found

```bash
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:
```json
{
  "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