bluefly/api_normalizer

API standardization and normalization layer for multi-provider AI services

0.1.0 2025-07-27 17:46 UTC

Requires

• php: >=8.1
• drupal/core: ^10.3 || ^11
• drupal/openapi: ^2.3
• drupal/openapi_jsonapi: ^3.0
• drupal/simple_oauth: ^6.0

Requires (Dev)

• drupal/coder: ^8.3
• drupal/core-dev: ^10.3 || ^11
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0
• squizlabs/php_codesniffer: ^3.7

Suggests

• drupal/ai: AI framework for Drupal
• drupal/encrypt: Field encryption for sensitive data
• drupal/field_group: Group fields in forms and displays
• drupal/health_check: Health check endpoints for services
• drupal/jsonapi_extras: Enhanced JSON:API functionality
• drupal/key: Secure API key storage
• drupal/migrate_plus: Advanced migration capabilities
• drupal/migrate_tools: Migration tools for data import
• drupal/monitoring: Advanced monitoring and alerting
• drupal/openapi_ui: OpenAPI UI for API documentation
• drupal/queue_ui: Queue management interface
• drupal/redis: Redis caching backend for performance
• drupal/views_bulk_operations: Bulk operations on entities

GPL-2.0-or-later

• Bluefly Collective

• api
• drupal
• providers
• normalization
• ai
• standardization

README

API normalization and transformation module for Drupal with comprehensive GraphQL integration (merged from graphql_integration).

Features

• Enterprise-grade architecture
• Comprehensive test coverage
• Security hardened
• Accessibility compliant (WCAG AA)
• Performance optimized
• Full API documentation
• GraphQL integration (merged from graphql_integration)
• AI-powered schema mapping
• OpenAPI schema management

Repository Information

• Type: Drupal Module (Git Submodule)
• GitLab URL: https://gitlab.bluefly.io/llm/api_normalizer
• Submodule Path: web/modules/custom/api_normalizer
• Local Path: /Users/flux423/Sites/LLM/llm-platform/web/modules/custom/api_normalizer

Integration Steps

1. Navigate to Individual Repository

   # This module is a git submodule, work in its individual repo
   cd /path/to/individual/api_normalizer/repository
   

2. Copy OpenAPI Specification

   cp openapi.yaml ./
   

3. Create Contract Testing Structure

   mkdir -p tests/src/Functional
   mkdir -p tests/features
   

4. Add PHPUnit Configuration

   <!-- phpunit.xml -->
   <testsuite name="api_normalizer API Contract Tests">
     <directory>tests/src/Functional</directory>
     <file>tests/src/Functional/*ApiContractTest.php</file>
   </testsuite>
   

5. Configure JSON:API Entities

   # JSON:API is built into Drupal 10 core, just needs configuration
   drush en rest restui serialization hal -y
   drush cr
   

6. Update GitLab CI

   include:
     - component: gitlab.bluefly.io/llm/gitlab_components/components/ci-cd/drupal/template@latest
     - component: gitlab.bluefly.io/llm/gitlab_components/components/testing/comprehensive-testing@latest
      
   drupal_api_validation:
     extends: .drupal_base
     script:
       - drush en rest restui serialization hal -y
       - drush cr
       - vendor/bin/phpunit tests/src/Functional/*ApiContractTest.php
   

7. Commit Changes

   git add .
   git commit -m "feat: implement API-first architecture for Drupal module
      
   - Add OpenAPI 3.1 specification with JSON:API endpoints
   - Implement PHPUnit contract tests
   - Configure REST and JSON:API endpoints
   - Enable API-first development workflow
      
   🤖 Generated with API-First Transformation
      
   Co-Authored-By: Claude <[e-mail]>"
   git push origin main
   

JSON:API Endpoints

• Entities: /jsonapi/api_normalizer/api_normalizer
• Custom API: /api/v1/api_normalizer/*
• Health Check: /api/v1/api_normalizer/health

Production Deployment

• Main Platform: https://llm.llm.bluefly.io/api/v1/api_normalizer
• JSON:API: https://llm.llm.bluefly.io/jsonapi/api_normalizer
• Documentation: https://docs.llm.bluefly.io/api-docs/api_normalizer

Local Development

• Main Platform: https://llm.local.bluefly.io/api/v1/api_normalizer
• JSON:API: https://llm.local.bluefly.io/jsonapi/api_normalizer
• Port Access: http://llm.local.bluefly.io:33000/api/v1/api_normalizer

API-First TDD Development Workflow

This module follows the LLM Platform's API-first, test-driven development approach using TDDAI.

Development Commands

# Comprehensive Drupal module analysis (includes UI/UX assessment)
cd web/modules/custom/api_normalizer
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js drupal audit . --comprehensive \
  --analyze-ui-components \
  --check-entity-definitions \
  --review-views-displays \
  --assess-admin-interfaces \
  --identify-missing-frontend \
  --create-ux-improvement-plan

# Alternative: Use analyze command with Drupal-specific prompts
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js analyze . --context drupal-contrib \
  --prompts "ui-components,entity-configs,views-displays,admin-forms,frontend-gaps,ux-plan"

# Start TDD cycle for this module
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js tdd cycle --context drupal-module

# Write failing tests first (RED)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js test-gen --module api_normalizer
../../../vendor/bin/phpunit tests/src/Unit/

# Implement minimal code (GREEN)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js generate service <ServiceName> --module api_normalizer --tdd

# Refactor and optimize (REFACTOR)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js improve fix --all --module api_normalizer

# Full contrib-ready assessment (all quality gates)
node /Users/flux423/Sites/LLM/common_npm/tddai/dist/cli.js drupal ultra-strict . \
  --contrib-ready \
  --ui-analysis \
  --performance-check \
  --accessibility-audit

# Standards and quality checks
../../../vendor/bin/phpcs --standard=Drupal,DrupalPractice src/
../../../vendor/bin/phpstan analyse src/

API Standards

• ✅ REST API endpoints with OpenAPI 3.1 specification
• ✅ GraphQL schema extensions where applicable
• ✅ 95% test coverage requirement
• ✅ Drupal 10/11 best practices compliance
• ✅ Service-based architecture with dependency injection

See main project README for complete workflow documentation.