> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quixa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Maturity & Governance Scorecard

> Comprehensive 5-pillar OpenAPI quality scoring, adaptive weight normalization, compliance tiering, and contract progression tracking.

# API Maturity & Governance Scorecard

The **Quixa API Maturity & Governance Scorecard** provides automated, real-time quality evaluation and contract resilience tracking for every registered OpenAPI / Swagger collection across your enterprise ecosystem.

Instead of manual design reviews or fragmented linting tools, Quixa analyzes specifications across 5 foundational pillars, normalizes weights adaptively, awards compliance tiers (such as *Amethyst*, *Gold*, and *Silver*), and records a historical time-series ledger to track API design improvements over time.

***

## The 5 Governance Pillars

Every specification uploaded to or synchronized with Quixa is evaluated against 5 core dimensions:

| Pillar | Default Weight | Key Evaluation Criteria |
| :- | :- | :- |
| **Security & Auth** | **25% – 30%** | Dedicated `securitySchemes` (OAuth2, Bearer JWT, API Key), top-level & operation-level security requirements, no sensitive plain-text parameters (`password`, `apikey`) in query/path strings. |
| **Documentation** | **20% – 25%** | Info summary & description richness, operation `summary` & `description` completeness, parameter documentation, response descriptions, and tag assignments. |
| **REST Standards** | **20% – 25%** | Conventional HTTP verbs (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`), camelCase/kebab-case URL path formatting, pluralized resource nouns, proper HTTP status codes (`200`, `201`, `204`, `400`, `401`, `404`, `500`), and standardized pagination parameters. |
| **Schema & SDK Readiness** | **20%** | Explicit response & request schemas, component schema reusability via `$ref`, typed properties (`type`, `format`), required field constraints, and field-level examples. |
| **Drift & Change Resilience** | **15% (Adaptive)** | Contract stability across revisions, detection of breaking changes (e.g. removed endpoints or altered properties), graceful deprecation notice (`deprecated: true`), and evolutive synchronization. |

***

## Adaptive Weight Normalization

In real-world enterprise architectures, not all APIs are configured for continuous remote drift detection immediately (e.g., local manual uploads or staging mock specs).

To ensure developer fairness and prevent penalization:

> \[!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

Quixa calculates a unified quality score (0–100) and assigns an enterprise compliance tier and letter grade:

```mermaid theme={null}
graph LR
    Score["Total Score (0 - 100)"]
    Score --> Amethyst["Score >= 90 ➔ Amethyst (Grade A+)"]
    Score --> Gold["Score 80 - 89 ➔ Gold (Grade A)"]
    Score --> Silver["Score 70 - 79 ➔ Silver (Grade B/B+)"]
    Score --> Bronze["Score 55 - 69 ➔ Bronze (Grade C)"]
    Score --> Iron["Score < 55 ➔ Iron (Grade D/F)"]
```

| Tier | Score Range | Metallic Identity | Quality Characterization |
| :- | :- | :- | :- |
| **Amethyst** | `90 - 100` | 💎 Radiant Gemstone (`#e879f9`) | **Optimizing Level.** Continuous governance, full automation, Zero-Trust compliance, and resilient drift management. |
| **Gold** | `80 - 89` | 🏆 24K Gold Trophy (`#fbbf24`) | **Managed & Standardized.** Solid contract standards, plural resources, active versioning strategy, and client SDK readiness. |
| **Silver** | `70 - 79` | 🛡️ Specular Chrome Silver (`#ffffff`) | **Defined Baseline.** Standardized documentation, core security schemes defined, with minor conventions or error response gaps. Features real silver luster and specular glow. |
| **Bronze** | `55 - 69` | 🎖️ Burnished Copper Medal (`#fb923c`) | **Repeatable Baseline.** Functional endpoints but lacks complete error definitions, versioning segments, or schema reuse. |
| **Iron** | `0 - 54` | 🛠️ Industrial Tempered Steel (`#cbd5e1`) | **Initial / Ad Hoc Base.** Processes are unpredictable, manual, and chaotic. Immediate remediation required. |

> \[!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

In addition to tiers, specifications meeting stringent pillar requirements receive verifiable metadata 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

To preserve maximum canvas focus and streamline navigation, the scorecard does not add clutter to your primary sidebar:

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

The API Maturity Scorecard is an enterprise governance module that can be toggled per tenant via the **Backoffice Portal**:

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

Enterprise platform engineers can query and trigger maturity calculations programmatically:

### 1. Get Latest Maturity Score

```http theme={null}
GET /api/gateway/collections/{collectionId}/maturity
Authorization: Bearer qxa_live_YOUR_KEY
```

**Response (200 OK):**

```json theme={null}
{
  "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

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

### 3. Force Recalculation

```http theme={null}
POST /api/gateway/collections/{collectionId}/maturity/calculate
Authorization: Bearer qxa_live_YOUR_KEY
Content-Type: application/json

{
  "isEvolutive": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.