​

API Maturity & Governance Scorecard

​

The 5 Governance Pillars

​

Adaptive Weight Normalization

[!NOTE] Dynamic Weight Normalization: When a collection is static or does not have active evolutive drift tracking configured:

• The Drift & Change Resilience category is deferred.
• The remaining 4 static categories automatically normalize to 100% total weight (Security: 30%, Documentation: 25%, REST Standards: 25%, Schema Readiness: 20%).
• As soon as scheduled drift monitoring is enabled, the scoring engine smoothly shifts to the 5-pillar distribution with 15% dedicated to contract change resilience.

​

Compliance Tiers & Dynamic Tags

[!TIP] Interactive Expandable Tier Cards: In both the widescreen scorecard view and the slide-over drawer, each compliance tier card is interactively expandable. Clicking any card header smoothly expands its operational definitions, compliance expectations, and maturity benchmarks.

​

Dynamic Compliance Tags

• #ZeroTrustReady: Security pillar score >= 90 with granular authentication schemes on all endpoints.
• #SdkOptimized: Schema pillar score >= 85 with complete component reusability and typed models.
• #RfcCompliant: REST standards score >= 85 with uniform path, plural naming, and status code conventions.
• #ChangeResilient: Drift resilience score >= 85 with zero breaking changes across revisions.
• #ZeroCriticalIssues: Specification contains zero critical security or contract integrity flaws.
• #EnterpriseGrade: Specification achieves Total Maturity Score >= 95 in the Amethyst Tier.
• #IronTier: Specification is in the Iron Base level (score < 55) requiring fundamental governance intervention.

​

Viewing the Scorecard in Quixa

​

Zero Left-Rail Clutter & Real-Time Sync

1. Tree Micro-Badge: Each collection displays a sleek chip indicating its tier and score (e.g. [ B+ • 72% ]).
2. Real-Time Reactive Synchronization: When you trigger a recalculation from either the drawer or the standalone page, the tree badge immediately reflects the fresh score via reactive event dispatch (quixa:maturity-score-updated) without requiring a manual page reload.
3. One-Click Slide-Over Drawer: Clicking any badge opens the in-app governance drawer:
   • Hero Gauge: Instant visual indicator of overall score, metallic tier icon, and compliance tags.
   • Full-Width Responsive Charts: Stacked single-column layout preventing horizontal scrollbars, featuring the 5-pillar Radar pentagon and time-series progression line chart.
   • Collapsible Actionable Quick Wins: Collapsed by default for scannability; expands to reveal ranked concrete fixes with potential point gains (e.g. +5 pts) and code resolution snippets.
   • Expandable Enterprise Maturity Tiers: Clickable reference cards to inspect compliance criteria directly from the drawer.
4. Dedicated Full-Page Scorecard (/collections/:id/scorecard): Clicking Open Full Page opens a dedicated widescreen view featuring:
   • High-definition radar polygon & historical chart
   • Tab 1: Comprehensive issue ledger filterable by severity and category
   • Tab 2: Enterprise Governance Methodology Guide, complete with mathematical weighting formulas, interactive tier cards, and dynamic compliance tag references.
5. Dashboard Macro Overview Widget (/dashboard):
   • The main Dashboard overview features a collapsible “API Quality & Governance Overview” widget.
   • Summarizes portfolio-wide average quality score, evaluated vs registered API count (100% normalized), active quick win findings, and direct links to view individual scorecards.
6. On-Demand Recalculate: Hit Recalculate at any time to re-evaluate the spec against the latest governance rulebook.

​

Enterprise Monetization & Feature Flag

1. Navigate to Backoffice ➔ Tenants ➔ Platform Components.
2. Locate API Maturity & Governance Scorecard (apiMaturityScorecard).
3. Toggle the feature on or off. When disabled, the badge, drawer, and endpoints remain completely hidden from standard tenant users.

​

REST API Reference

​

1. Get Latest Maturity Score

GET /api/gateway/collections/{collectionId}/maturity
Authorization: Bearer qxa_live_YOUR_KEY

{
  "collectionId": "col_customer_api_v1",
  "totalScore": 88,
  "grade": "A",
  "tier": "Gold",
  "tags": ["ZeroTrustReady", "SdkOptimized"],
  "isEvolutive": false,
  "categories": [
    {
      "categoryKey": "security",
      "displayName": "Security & Auth",
      "score": 95,
      "weight": 0.3,
      "status": "optimal"
    },
    {
      "categoryKey": "documentation",
      "displayName": "Documentation",
      "score": 85,
      "weight": 0.25,
      "status": "optimal"
    },
    {
      "categoryKey": "rest_standards",
      "displayName": "REST Standards",
      "score": 82,
      "weight": 0.25,
      "status": "good"
    },
    {
      "categoryKey": "schema_integrity",
      "displayName": "Schema Integrity",
      "score": 90,
      "weight": 0.2,
      "status": "optimal"
    }
  ],
  "issues": [
    {
      "id": "rest_missing_error_responses",
      "category": "rest_standards",
      "severity": "warning",
      "title": "Missing 4xx/5xx Error Schemas",
      "description": "Operation GET /customers does not define explicit 400 or 500 responses.",
      "impactPoints": 5,
      "recommendation": "Add standard RFC 7807 Problem Details error responses."
    }
  ],
  "evaluatedAt": "2026-10-18T10:30:00Z"
}

​

2. Get Historical Progression

GET /api/gateway/collections/{collectionId}/maturity/history?limit=10
Authorization: Bearer qxa_live_YOUR_KEY

​

3. Force Recalculation

POST /api/gateway/collections/{collectionId}/maturity/calculate
Authorization: Bearer qxa_live_YOUR_KEY
Content-Type: application/json

{
  "isEvolutive": true
}