# API Normalization GraphQL Integration

GraphQL support for API Normalization using the Drupal GraphQL module.

## Overview

API Normalization GraphQL Integration is a **submodule** that exposes normalized API data through GraphQL queries and mutations, leveraging the powerful Drupal GraphQL module.

## Features

- GraphQL queries for normalized API data
- GraphQL mutations for API operations
- Schema builder integration
- Type definitions for normalized responses
- Resolver implementations
- Support for all API Normalization providers

## Requirements

- Drupal 10.3+ or 11.x
- API Normalization (parent module)
- **GraphQL module** (`graphql/graphql`) - Required contrib module

## Installation

```bash
# Install GraphQL module first
composer require drupal/graphql

# Enable modules
drush en api_normalization graphql api_normalization_graphql
```

## Configuration

1. Navigate to **Admin > Configuration > Web Services > GraphQL**
2. Create or edit a GraphQL server
3. Enable API Normalization schema extensions
4. Configure query/mutation permissions

## Usage

### GraphQL Queries

Query normalized API data through GraphQL:

```graphql
query {
  apiNormalizedResponse(provider: "openai", endpoint: "chat") {
    data {
      content
      model
      tokens
    }
    metadata {
      provider
      timestamp
      status
    }
  }
}
```

### GraphQL Mutations

Execute API operations:

```graphql
mutation {
  executeNormalizedApi(
    provider: "anthropic"
    endpoint: "messages"
    payload: {
      model: "claude-3-sonnet"
      messages: [{role: "user", content: "Hello"}]
    }
  ) {
    success
    data {
      content
      model
    }
    errors
  }
}
```

## Schema Overview

### Types

- **ApiNormalizedResponse**: Normalized API response wrapper
- **ApiProvider**: API provider metadata
- **ApiEndpoint**: Available endpoint information
- **ApiError**: Error information

### Queries

- `apiNormalizedResponse`: Fetch normalized API data
- `apiProviders`: List available providers
- `apiEndpoints`: List available endpoints

### Mutations

- `executeNormalizedApi`: Execute API request
- `batchNormalizedApi`: Batch API operations

## GraphQL Schema Builder

This module extends the GraphQL Schema Builder with:

1. **Data Producers**: For API Normalization data
2. **Type Extensions**: For normalized response types
3. **Field Resolvers**: For API data resolution

## Integration Examples

### JavaScript/React

```javascript
import { useQuery } from '@apollo/client';

const GET_API_DATA = gql`
  query GetApiData($provider: String!) {
    apiNormalizedResponse(provider: $provider) {
      data {
        content
      }
    }
  }
`;

function ApiComponent() {
  const { data, loading } = useQuery(GET_API_DATA, {
    variables: { provider: 'openai' }
  });

  return <div>{data?.apiNormalizedResponse?.data?.content}</div>;
}
```

### Gatsby

```javascript
export const query = graphql`
  query {
    apiNormalization {
      apiProviders {
        name
        status
        endpoints {
          name
          path
        }
      }
    }
  }
`;
```

## Performance

### Caching

Enable GraphQL query caching:

```yaml
# In your GraphQL server configuration
caching:
  query: true
  metadata: true
  ttl: 3600
```

### DataLoader

This module supports DataLoader pattern for batch loading:

```graphql
# Multiple API calls batched automatically
query {
  provider1: apiNormalizedResponse(provider: "openai") { ... }
  provider2: apiNormalizedResponse(provider: "anthropic") { ... }
  provider3: apiNormalizedResponse(provider: "ollama") { ... }
}
```

## Related Modules

- **api_normalization** - Parent module (required)
- **graphql** - Drupal GraphQL module (required)
- **api_normalization_ui** - Enhanced UI components
- **api_normalization_feeds** - Feeds integration

## Troubleshooting

### Schema Not Available

1. Clear Drupal cache: `drush cr`
2. Rebuild GraphQL schema in admin UI
3. Check module is enabled: `drush pml | grep graphql`

### Resolver Errors

Check:
1. API Normalization is properly configured
2. API credentials are valid
3. GraphQL server permissions are correct
4. Check watchdog logs: `drush wd-show`

## Documentation

- [API Normalization Documentation](../../README.md)
- [GraphQL Module Documentation](https://www.drupal.org/docs/contributed-modules/graphql)
- [GraphQL API Reference](https://graphql.org/learn/)

## Advanced Usage

### Custom Resolvers

Extend resolvers for custom API operations:

```php
/**
 * Custom resolver for specialized API operations.
 */
class CustomApiResolver extends ApiNormalizationResolverBase {
  public function resolve($value, $args, ResolveContext $context, ResolveInfo $info) {
    // Custom resolution logic
  }
}
```

### Schema Extensions

Add custom types to the GraphQL schema:

```php
/**
 * Extends GraphQL schema with custom API types.
 */
class CustomSchemaExtension extends SdlSchemaExtensionPluginBase {
  public function getSchemaDefinition() {
    return "extend type Query { customApiQuery: CustomType }";
  }
}
```

## Support

- Issue queue: https://www.drupal.org/project/issues/api_normalization
- GraphQL documentation: https://www.drupal.org/docs/contributed-modules/graphql

## License

GPL-2.0-or-later
