API Normalization
=================

Provides a comprehensive API development framework for Drupal with OpenAPI 3.1
schema import, validation, multi-provider routing, and enterprise-grade features
including circuit breakers, failover, multi-tenancy, and RBAC.


INTRODUCTION
------------

The API Normalization module enables Drupal to act as a sophisticated API
gateway and development platform. It provides tools for importing OpenAPI 3.1
specifications, testing API endpoints, managing multiple API providers with
automatic failover, and implementing enterprise security patterns.

 * For a full description of the module, visit the project page:
   https://www.drupal.org/project/api_normalization

 * To submit bug reports and feature suggestions, or track changes:
   https://www.drupal.org/project/issues/api_normalization


REQUIREMENTS
------------

This module requires the following:

 * Drupal 10.3 or higher, or Drupal 11
 * PHP 8.1 or higher
 * Composer

The following contributed modules extend functionality:

 * JSON:API (core) - API endpoint generation
 * OpenAPI UI - Interactive API documentation (recommended)
 * Key - Secure API key management (recommended)


INSTALLATION
------------

Install as you would normally install a contributed Drupal module. For further
information, see:
https://www.drupal.org/docs/extending-drupal/installing-modules

Using Composer (recommended):

    composer require drupal/api_normalization
    drush en api_normalization


CONFIGURATION
-------------

1. Navigate to Administration > Configuration > Web Services > API Normalization
   (/admin/config/services/api-normalization)

2. Configure API providers and endpoints

3. Set up circuit breaker thresholds and failover rules

4. Configure multi-tenancy settings if using multi-site

5. Assign API permissions to user roles


FEATURES
--------

Core Features:
 * OpenAPI 3.1 schema import and validation
 * Interactive API endpoint testing interface
 * Schema validation against OpenAPI specifications
 * Automatic endpoint discovery and configuration

Enterprise Features:
 * Provider Registry - Manage multiple API providers with priority ordering
 * Circuit Breaker - Automatic failure detection and recovery
 * Provider Failover - Seamless fallback to backup providers
 * Multi-Tenancy - Isolated API configurations per tenant
 * RBAC - Fine-grained role-based access control (80+ permissions)
 * Rate Limiting - Request throttling and quota management
 * Field-Level Security - Control access to individual API fields
 * Gateway Routing - URL rewriting and request transformation
 * Audit Logging - Comprehensive API activity tracking

Developer Features:
 * Endpoint Resolver - Dynamic endpoint discovery with caching
 * API Testing UI - Built-in endpoint testing with request/response inspection
 * Schema Validation - Real-time validation against OpenAPI specs
 * Error Handling - Structured error responses with detailed logging


USAGE
-----

Importing an OpenAPI Schema:

1. Navigate to /admin/api-normalization/import
2. Enter the OpenAPI schema URL or paste the JSON/YAML specification
3. Click "Import Schema" to validate and import
4. Configure generated endpoints

Testing an API Endpoint:

1. Navigate to /admin/api-normalization/test
2. Enter the endpoint URL and select HTTP method
3. Add headers and request body if needed
4. Click "Send Request" to test
5. View response with syntax highlighting

Configuring Provider Failover:

1. Navigate to /admin/api-normalization/providers
2. Add multiple providers for the same service
3. Set priority order and failover rules
4. Configure circuit breaker thresholds
5. Test failover by disabling primary provider


PERMISSIONS
-----------

The module provides granular permissions including:

 * Administer API normalization - Full administrative access
 * Access API testing interface - Use the endpoint testing UI
 * Import OpenAPI schemas - Import and validate schemas
 * Manage API providers - Configure provider registry
 * View API audit logs - Access activity logs
 * Configure circuit breakers - Set failure thresholds
 * Manage tenants - Multi-tenancy administration

Additional permissions for field-level access, gateway routes, and
provider-specific operations. See Permissions page for full list.


TROUBLESHOOTING
---------------

 * If schemas fail to import, verify the URL is accessible and returns valid
   OpenAPI 3.1 JSON or YAML.

 * If endpoints return 403 errors, check user permissions and RBAC
   configuration.

 * If circuit breakers remain open, verify provider connectivity and check
   /admin/reports/dblog for detailed error messages.

 * For multi-tenancy issues, ensure tenant configurations don't conflict and
   domain patterns are correctly specified.


MAINTAINERS
-----------

Current maintainers:
 * API Normalization Maintainers - https://www.drupal.org/project/api_normalization

This project has been sponsored by:
 * Bluefly.io - https://www.bluefly.io
