README

OpenAPI import orchestrator that leverages JSON:API, OpenAPI, and other contrib modules to generate entities with comprehensive management and tampering capabilities.

Overview

The API Normalizer module provides a comprehensive solution for standardizing API responses across different AI/LLM providers. It ensures consistent data structures, error handling, and response formats regardless of which AI provider you're using, making it easier to switch between providers or use multiple providers simultaneously.

Features

Multi-Provider Support: Normalize responses from OpenAI, Anthropic, Ollama, LangChain, and more
Token Management: Centralized token management with ~/.tokens directory integration
Response Standardization: Convert all provider responses to a unified format
Error Normalization: Consistent error handling and mapping across providers
OpenAPI Integration: Import and manage OpenAPI schemas
JSON:API Support: Full integration with Drupal's JSON:API
Provider Dashboard: Real-time status monitoring for all configured providers
Configurable Settings: Extensive admin interface for customization
Caching Layer: Built-in response caching for performance
Rate Limiting: Provider-specific rate limiting

Requirements

Drupal 10.3 or higher / Drupal 11
PHP 8.1 or higher
JSON:API module (core)
REST module (core)
Serialization module (core)

Suggested Modules

For enhanced functionality, consider installing:

JSON:API Resources - Advanced JSON:API features
OpenAPI UI - Interactive API documentation
Simple OAuth - OAuth2 authentication
HTTP Client Manager - Advanced HTTP client features

Installation

Install via Composer:

composer require bluefly/api_normalizer

Enable the module:
```
drush en api_normalizer
```
Configure at /admin/config/services/api-normalizer

Configuration

Token Management

Navigate to Configuration > Services > API Normalizer > Token Management:

Token Directory: Set the directory path for token files (default: ~/.tokens)
Auto-load Tokens: Enable automatic token loading from directory
Token Validation: Toggle token format validation
Environment Fallback: Allow fallback to environment variables
File Extensions: Configure accepted token file extensions

Provider Configuration

Each AI provider can be configured with:

API endpoints
Authentication methods
Rate limits
Response caching
Custom field mappings

Setting Up Tokens

Create token files in your configured directory:

# Create tokens directory
mkdir ~/.tokens

# Add provider tokens
echo "sk-your-openai-key" > ~/.tokens/openai
echo "your-anthropic-key" > ~/.tokens/anthropic
echo "your-custom-key" > ~/.tokens/custom_provider

Usage

Basic Normalization

// Get the normalizer service
$normalizer = \Drupal::service('api_normalizer.service');

// Normalize a provider response
$providerResponse = [
  'choices' => [
    ['text' => 'AI response', 'finish_reason' => 'stop']
  ],
  'usage' => ['total_tokens' => 150]
];

$normalized = $normalizer->normalize($providerResponse, 'openai');

Standard Response Format

All normalized responses follow this structure:

[
  'success' => true,
  'data' => [
    'response' => 'AI response text',
    'model' => 'gpt-4',
    'provider' => 'openai',
    'usage' => [
      'prompt_tokens' => 100,
      'completion_tokens' => 150,
      'total_tokens' => 250,
    ],
  ],
  'metadata' => [
    'request_id' => 'uuid-string',
    'timestamp' => 1234567890,
    'duration_ms' => 1500,
    'normalized_at' => '2024-01-01T00:00:00Z',
  ],
  'errors' => [],
]

Error Handling

Errors are standardized across all providers:

try {
  $response = $normalizer->normalize($data, 'provider');
} catch (NormalizationException $e) {
  $error = [
    'success' => false,
    'errors' => [
      [
        'code' => $e->getCode(),
        'message' => $e->getMessage(),
        'provider' => $e->getProvider(),
        'original_error' => $e->getOriginalError(),
      ]
    ]
  ];
}

Provider Status Check

// Check provider availability
$providerManager = \Drupal::service('api_normalizer.provider_manager');
$status = $providerManager->getProviderStatus('openai');

if ($status['available']) {
  // Provider is ready
  $token_status = $status['token_status'];
  $health = $status['health_check'];
}

API Endpoints

The module provides several API endpoints:

Provider Status

GET /api/normalizer/status
GET /api/normalizer/status/{provider}

Normalization Test

POST /api/normalizer/test
{
  "provider": "openai",
  "response": {...}
}

Schema Management

GET /api/normalizer/schemas
POST /api/normalizer/schemas/import

Extending the Module

Creating Custom Normalizers

namespace Drupal\my_module\Normalizer;

use Drupal\api_normalizer\Normalizer\NormalizerInterface;

class MyProviderNormalizer implements NormalizerInterface {
  
  public function normalize($response, array $context = []) {
    return [
      'success' => true,
      'data' => [
        'response' => $this->extractResponse($response),
        'model' => $this->extractModel($response),
        'provider' => 'my_provider',
        'usage' => $this->extractUsage($response),
      ],
      'metadata' => $this->generateMetadata($context),
      'errors' => [],
    ];
  }
  
  public function supports($provider) {
    return $provider === 'my_provider';
  }
}

Registering Custom Normalizers

In my_module.services.yml:

services:
  my_module.my_provider_normalizer:
    class: Drupal\my_module\Normalizer\MyProviderNormalizer
    tags:
      - { name: api_normalizer }

Dashboard Features

The module includes a comprehensive dashboard at /admin/config/services/api-normalizer/dashboard:

Provider Status: Real-time availability monitoring
Token Status: Visual indicators for token configuration
Performance Metrics: Response time and success rate tracking
Error Logs: Recent errors and debugging information
Quick Actions: Enable/disable providers, clear caches

Troubleshooting

Token Not Found

Check token file exists in configured directory
Verify file permissions (readable by web server)
Ensure correct file extension (.token, .txt, or configured)
Check environment variable fallback is enabled

Provider Not Available

Verify token is valid
Check provider endpoint is accessible
Review provider-specific configuration
Check rate limiting hasn't been exceeded

Normalization Errors

Enable debug mode in settings
Check Drupal logs at /admin/reports/dblog
Verify response format matches expected structure
Test with known-good responses

Performance Optimization

Enable response caching for repeated queries
Configure appropriate cache TTL per provider
Use batch processing for multiple requests
Monitor rate limits to avoid throttling

Security Considerations

Store tokens securely (never in version control)
Use Key module for production environments
Implement proper access controls
Regular token rotation
Monitor for suspicious activity

Support

Issue Queue: https://github.com/bluefly/api_normalizer/issues
Documentation: https://docs.bluefly.dev/api-normalizer
Packagist: https://packagist.org/packages/bluefly/api_normalizer

License

This project is licensed under the GPL-2.0-or-later license.

bluefly / api_normalizer

Maintainers

Details