Runtime Capability Authority ADR: API Normalization (api_normalization)¶
1. Capability Inventory¶
Governance must always begin with the capability inventory. Only after the capability exists can you compare it against the ecosystem.
- Capability: API Normalization & Lifecycle Management
- Purpose: Complete API lifecycle management for Drupal—import any OpenAPI specification, generate entities from schemas, proxy requests with enterprise features (caching, circuit breaker), normalize AI provider responses (OpenAI, Anthropic, Ollama), and auto-expose via JSON:API/GraphQL.
- Consumers: External systems consuming normalized APIs, Internal AI orchestration tools, ECA workflows.
- Inputs: OpenAPI specifications (YAML/JSON), External API responses.
- Outputs: Generated Drupal entities (real, not virtual), Normalized API responses (JSON:API / GraphQL), Workflow events.
- Protocols: HTTP/REST, JSON:API, GraphQL, OpenAPI 3.x.
- Persistence: Standard Drupal database (generated entities with fields).
- Security: Proxy includes rate limiting and circuit breakers. Multi-provider token management with SHA256 hashing.
- Dependencies:
drupal:serialization,drupal:rest,drupal:jsonapi. - Configuration: Configured via wizard for OpenAPI imports.
- Runtime: Synchronous HTTP request/response pipeline via Proxy mode.
2. Authority Evaluation Order¶
Evaluate authorities in order, then record the stopping point.
Order of Evaluation: Business Capability → Drupal Core → Drupal CMS → Drupal Contrib → Composer Ecosystem → OSSA → Bluefly Extension → Bluefly Product
Stopped at: Drupal Contrib Reason: This module is a Strategic Platform Capability targeted for open-source publication on Drupal.org. It must serve as a generalized ecosystem primitive. It cannot contain proprietary Bluefly Product IP.
3. Native Capability Audit¶
Appears consistent with capabilities commonly provided by:
- Drupal Core: serialization, jsonapi, rest (for endpoints and formatting).
- Drupal Contrib: external_entities (Provides virtual external data bridging, but no local generation), openapi (Exports specs, does not import), http_client_manager (Generic HTTP wrappers).
4. Capability Comparison Matrix¶
| Feature | Current Custom Implementation (api_normalization) |
Candidate Ecosystem Primitive | Gap (Remaining Delta) |
|---|---|---|---|
| OpenAPI Schema Import | ✓ | ✗ (Contrib openapi only exports) |
Contrib Package Target |
| Entity Generation from API | ✓ | ✗ (external_entities is virtual only) |
Contrib Package Target |
| Proxy w/ Circuit Breaker | ✓ | ✗ (No native proxy in Drupal core) | Contrib Package Target |
| AI Provider Normalization | ✓ (OpenAI, Anthropic, Ollama) | ✗ | Contrib Package Target |
| Proprietary Business Logic | ✗ (Must be removed if present) | N/A | MUST EXTRACT TO WEBSITE LAYER |
| API Key Management | ✓ (Custom SHA256 hashing) | ✓ (Contrib key module) |
Overlap (Needs alignment) |
5. Current Assessment¶
- Candidate Delta: PACKAGE (Drupal Contrib)
- Confidence: HIGH
- Reason: The capability operates in a unique space (import, generate, proxy, normalize). As a module destined for contrib publication, it must be thoroughly cleansed of any site-specific configuration or proprietary IP (which belongs in specific websites like ContextControl). It must also rely on existing contrib primitives (like the
keymodule) rather than rolling its own.
6. Governance Outcome & Evidence Gates¶
Target Outcome: Candidate Package / Upstream
Evidence Checklist (Enhancement Pipeline): - [x] Capability inventoried - [x] Authority identified (Drupal Contrib Publication Target) - [x] Remaining delta defined (Contrib features vs Proprietary IP extraction) - [ ] Enhancement plan drafted (Focus on stripping proprietary IP and generalizing for Contrib) - [ ] Implementation validated - [ ] Receipt
Implementation Decision: Draft the Enhancement Plan to strictly audit the module for proprietary IP. Any IP must be extracted to the website layer. Duplicate generic logic (like key management) must be refactored to use standard contrib modules. The remaining clean core will be prepared for Drupal.org publication.