API Contract

Stell Dir vor, Du beauftragst einen Handwerker: Bevor er anfängt, besprecht ihr genau, was gemacht werden soll, welche Materialien verwendet werden und was das Ergebnis sein soll. Ein API Contract ist genau so eine Vereinbarung - nur zwischen Software-Systemen.

Was ist das Problem?

Wenn zwei Systeme miteinander kommunizieren, kann viel schiefgehen: Das eine System sendet Daten in einem Format, das andere erwartet etwas völlig anderes. Ohne klare Absprache entstehen Fehler, die oft erst im laufenden Betrieb auffallen - und dann teuer werden.

Die Lösung: Der API Contract

Ein API Contract (Application Programming Interface Contract) ist eine formale Vereinbarung, die exakt festlegt:

Welche Endpunkte existieren
Welche Daten gesendet und empfangen werden
Welche Formate und Typen gelten
Welche Fehler auftreten können

Vollständiges Beispiel

Hier ein API Contract für einen Benutzer-Service im Mensch + KI-Code Prozess:

# API Contract: User Service
# Version: 1.0.0
# Status: active

contract:
  id: "api-user-service-v1"
  name: "User Service API Contract"
  version: "1.0.0"
  owner: "team-identity"

  # Endpunkt-Definition
  endpoints:
    - path: "/api/users/{id}"
      method: "GET"
      description: "Einzelnen Benutzer abrufen"

      # Request-Spezifikation
      request:
        parameters:
          - name: "id"
            in: "path"
            type: "integer"
            required: true
            validation:
              min: 1
              max: 2147483647

        headers:
          - name: "Authorization"
            type: "string"
            required: true
            pattern: "^Bearer [A-Za-z0-9-_]+$"

      # Response-Spezifikation
      response:
        success:
          status: 200
          content_type: "application/json"
          schema:
            type: "object"
            properties:
              id:
                type: "integer"
              email:
                type: "string"
                format: "email"
              name:
                type: "string"
                maxLength: 100
              created_at:
                type: "string"
                format: "datetime"

        errors:
          - status: 401
            code: "UNAUTHORIZED"
            message: "Authentifizierung erforderlich"
          - status: 404
            code: "USER_NOT_FOUND"
            message: "Benutzer nicht gefunden"

  # Prädikate für Gate-Prüfung
  predicates:
    - id: "has_valid_schema"
      check: "openapi_schema_valid"
    - id: "has_error_handling"
      check: "all_error_codes_documented"
    - id: "has_auth_defined"
      check: "authentication_specified"

  # SLA-Garantien
  sla:
    availability: "99.9%"
    max_response_time_ms: 200
    rate_limit: "1000/minute"

Wie wird der Contract geprüft?

Im Mensch + KI-Code Prozess durchläuft jeder API Contract automatische Prüfungen:

# Gate-Prüfung für API Contract
gate_check:
  gate_id: "G2_ANALYSIS"
  contract_id: "api-user-service-v1"

  results:
    - predicate: "has_valid_schema"
      passed: true
      evidence: "OpenAPI 3.0 Schema validiert"

    - predicate: "has_error_handling"
      passed: true
      evidence: "3 Error-Codes dokumentiert"

    - predicate: "has_auth_defined"
      passed: true
      evidence: "Bearer Token Auth spezifiziert"

  verdict: "PASS"
  timestamp: "2024-01-15T10:30:00Z"

Warum ist das wichtig?

Der API Contract schafft Vertrauen durch Transparenz. Beide Seiten - Mensch und KI, Frontend und Backend, Team A und Team B - wissen genau, was sie erwarten können. Änderungen werden versioniert, Breaking Changes sind sofort erkennbar.

Im Mensch + KI-Code Prozess: API Contracts werden in Phase 3 (Analysis) erstellt und am Gate G2 geprüft. Sie sind Teil des Contract-Artefakts und werden automatisch gegen die Implementierung validiert.