README

Admin Dashboard & Preview: The static AdminController (and its routes) have been removed. Use a Drupal View (or a custom block) for a dynamic admin dashboard and a config page (or a View) for a preview.

API Specs Listing (JSON Endpoint): The static ApiSpecController (and its route) have been removed. Use a core entity list (or a View) to list, edit, and delete API specs (for example, if you have a "ApiSpecification" config entity). If you need a JSON endpoint, consider using a REST or JSON:API resource (or a custom endpoint) that pulls data from your entity list.

Normalization Logs Listing: The static LogAdminController (and its route) have been removed. Use a core entity list (or a View) to list, filter, and export normalization logs (for example, if you have a "NormalizationLog" entity).

Routing Refinement (Optimized): The routing file (api_normalization.routing.yml) has been rigorously refined. Unused routes (for removed controllers (AdminController, ApiSpecAdminController, LogAdminController, ApiSpecController) and routes (api_normalization.dashboard, api_normalization.admin_dashboard, api_normalization.admin_preview, api_normalization.import_entities, api_normalization.api_explorer) (replaced by a View or config page)) have been removed. Only the OpenAPI (OpenApiController) (api_normalization.openapi_json, api_normalization.openapi, api_normalization.settings, api_normalization.settings_form, api_normalization.route_mapping_form) and Proxy (ApiProxyController) (api_normalization.proxy) routes remain (with granular permissions (for example, "access api normalization openapi json", "access api normalization openapi", "access api normalization proxy", "administer api normalization settings", "administer api normalization sources")).

This module provides OpenAPI-native API normalization and schema standardization for LLM, agent, and MCP services, with optional ECA and MCP integration.

Features

• Configurable default OpenAPI schema
• Admin dashboard and logs
• OpenAPI explorer and validated API endpoints
• Extensible for LLM model registry and contract validation

Configuration

• Go to Configuration > Development > API Normalization Settings
• Set the default OpenAPI schema URL

API

• OpenAPI spec: /openapi.json
• API Explorer: /admin/config/api-normalizer/explorer

Permissions

• administer api normalization settings: Configure API Normalization module settings.
• access api normalization openapi json: View the /openapi.json endpoint for API Normalization.
• access api normalization openapi: View the /api/normalization/openapi endpoint for API Normalization.
• access api normalization proxy: Use the /api/normalization/proxy endpoint for API Normalization.
• administer api normalization sources: Manage API Normalization route mappings and sources.

Extending

• Add plugins for new LLM adapters or schema processors

Tests

• See /tests for Kernel and Functional test stubs

Help

• See the Help page in the Drupal admin for usage and troubleshooting.

Overview

The API Normalizer module transforms Drupal into an OpenAPI-native platform, enabling contract-driven development, SDK generation, LLM/agent integration, and automated documentation. It provides strict OpenAPI 3.1 compliance, smart schema inference, and deep integration with Drupal entities, JSON:API, and REST resources.

Usage

1. Enable the module.
2. Visit /openapi.json to view the OpenAPI 3.1 contract for your site.
3. Use the admin UI at /admin/config/api_normalizer (coming soon) to preview and download schemas for any entity or resource.
4. Integrate with SDK generators, Postman, or LLM agents using the exported OpenAPI contract.

Extending

• Add schema overrides in *.schema.yml or via PHP attributes on entity/field classes.
• Implement custom normalizers in src/Normalizer/ or OpenAPI extensions in src/OpenApi/.
• Add new resource schema providers as plugins in src/Plugin/.

DevOps

@bluefly-todo: Update the GitLab CI job name to reflect the current component name.

• The module includes a GitLab CI job (openapi-lint.yml) to validate OpenAPI output.
• Artifacts can be published to GitLab Pages or S3 for downstream automation.

Roadmap

• Admin UI for schema preview, diff, and export
• Full support for all entity types and REST/JSON:API resources
• LLM/agent toolkit export
• More granular x-drupal-* extensions

Dynamic OpenAPI Generation

• Enumerates all entity types and bundles, generating OpenAPI schemas for each.
• All schemas are exported as reusable OpenAPI components.
• REST/JSON:API resource support coming soon.
• Extensible for LLM, SDK, and automation use cases.

Services

• api_normalization.openapi_builder: Builds the OpenAPI contract dynamically.
• api_normalization.entity_normalizer: Normalizes entities to OpenAPI schemas.
• api_normalization.schema_normalizer: Centralizes schema inference and overrides.
• api_normalization.extension_manager: Adds x-drupal-* OpenAPI extensions.

Admin UI Roadmap

• Entity/resource selector, live schema preview, diff/version compare, and download/export coming soon.

Environment Variables & Security Best Practices

This module is designed to support environment-variable-driven configuration for all sensitive values (API URLs, tokens, etc). If you add any external integrations or secrets, use environment variables and reference them in your services.yml as %env(MY_ENV_VAR)%.

Example .env file (for future use)

API_NORMALIZATION_API_URL=https://api.example.com/v1
API_NORMALIZATION_API_TOKEN=your-real-token

Never commit real secrets to version control. Document all required environment variables in this README if you add any.

License

GPL-2.0-or-later

Architecture

API Normalization includes a powerful derivation engine (formerly Entity Deriver) for automating plugin, field, and admin view generation from entity types or OpenAPI specs.

• Config Entity: DerivationDefinition stores each derivation's configuration
• Plugin Types:
  • DeriverInput: Defines the source (e.g., OpenAPI spec, entity type)
  • DeriverOutput: Defines what is produced (e.g., plugin, field, feed type, admin view)
  • DataMapper: Handles transformation/mapping, can integrate with Tamper
• DerivationManager: Service that executes derivations using the configured plugins

Usage (Expanded)

• Enable the module.
• Visit /openapi.json

Structure (Drupal 11 Best Practices)

• api_normalization/ (main module)
  • Core normalization logic, OpenAPI validation, and admin UI.
  • Minimal dependencies: system, serialization, openapi.
• api_normalization_eca/ (submodule)
  • ECA workflow and event integration for normalization events.
  • Depends on: eca, api_normalization.
  • Provides: Event subscriber for triggering ECA workflows on normalization events.
• api_normalization_mcp/ (submodule)
  • MCP and MCP Client integration for API source registration and pipeline triggers.
  • Depends on: mcp, mcp_client, api_normalization.
  • Provides: Event subscriber for registering API sources with MCP and triggering pipelines.

Enabling/Disabling Integrations

• Enable only the main module for core normalization features.
• Enable api_normalization_eca for ECA workflow automation.
• Enable api_normalization_mcp for MCP registration and pipeline integration.

Submodule Best Practices (Drupal 11)

• Submodules are placed as directories inside the main module.
• Each submodule has its own .info.yml and services.yml.
• Event subscribers and integration code are only loaded if the submodule is enabled.
• This keeps the main module lightweight and decoupled from optional integrations.

Development

• Follow strict type safety and OpenAPI alignment for all code.
• Add new integrations as submodules to avoid unnecessary dependencies in the main module.
• See ARCHITECTURE.md for more details on extensibility and event-driven design.