# API-Versionierung

Unser Ansatz zu API-Kompatibilität, inkompatiblen Änderungen und Beta-Phasen.

Wir möchten die aclipp API weiterentwickeln, ohne bestehende Integrationen unnötig zu Anpassungen zu zwingen. Dieser Leitfaden beschreibt unseren aktuellen Ansatz zu Kompatibilität und frühen Funktionen. Er bildet eine Grundlage, die wir mit der API weiterentwickeln, und ist keine Zusage eines festen Veröffentlichungsplans oder einer festen Supportdauer.

## Versionen und Kompatibilität

Die öffentliche REST API verwendet derzeit `/api/v1`. Die Version im Pfad bezeichnet den API-Vertrag, nicht jede Bereitstellung des Dienstes. Fehlerbehebungen und kompatible Erweiterungen können innerhalb dieser Version erscheinen.

Für stabile Endpunkte gilt unser Grundsatz, dass eine gültige Integration nach einer kompatiblen Änderung weiter funktionieren soll. Beispiele sind ein zusätzlicher Endpunkt oder ein optionaler Anfrageparameter, dessen Standardwert das bisherige Verhalten erhält. Clients sollten außerdem zusätzliche Antwortfelder tolerieren, statt eine Antwort wegen einer unbekannten Eigenschaft abzulehnen.

Kompatibilität betrifft auch das Verhalten, nicht nur die JSON-Struktur. Entfernte oder umbenannte Felder, neue Pflichtangaben, andere Feldtypen oder eine veränderte Bedeutung einer Operation können Integrationen beeinträchtigen. Auch zusätzliche Enum-Werte können Clients mit abschließender Fallunterscheidung betreffen. Nicht jede Ergänzung ist automatisch harmlos.

## Inkompatible Änderungen und Abkündigung

Bei einer geplanten inkompatiblen Änderung an einem stabilen Vertrag ist unser Ansatz, eine neue API-Version oder eine Ersatzoperation mit einem Migrationsweg einzuführen. Wir streben eine Vorankündigung an, die erklärt, was sich ändert, wie die Migration funktioniert und wann das bisherige Verhalten entfällt.

Eine allgemeine Ankündigungsfrist oder garantierte Lebensdauer je API-Version haben wir noch nicht festgelegt. Diese Angaben werden mit der jeweiligen Änderung konkretisiert. Dringende Sicherheits- oder Datenschutzkorrekturen können ein schnelleres Vorgehen erfordern.

## Entwicklungsphasen

Verfügbarkeit und Stabilität sind unterschiedliche Fragen. Eine Funktion kann allgemein verfügbar sein, während sich ihr Vertrag noch weiterentwickelt.

| Phase                                    | Verfügbarkeit                                            | Was du erwarten kannst                                               |
| ---------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| <ApiBetaBadge stability="closed-beta" /> | Ausgewählte Organisationen mit freigeschalteter Funktion | Frühes Feedback; Eingaben, Ausgaben und Verhalten können sich ändern |
| <ApiBetaBadge stability="beta" />        | Allgemein verfügbar                                      | Breitere Nutzung und Feedback; der Vertrag kann sich noch ändern     |
| Stabil, kein Badge                       | Verfügbar nach den üblichen Zugriffsregeln               | Der oben beschriebene Ansatz zu Kompatibilität und Migration gilt    |

Dieselben Badges stehen neben den Endpunkttiteln in der [API-Referenz](/docs/api-reference). Bewege den Mauszeiger darauf oder fokussiere sie mit der Tastatur, um die Erklärung zu lesen.

Closed-beta- und Beta-Endpunkte können sich ohne neue API-Version oder die für stabile Endpunkte vorgesehene Migrationsphase ändern. Plane bei ihrer Nutzung Anpassungen ein. Der Wechsel von Closed Beta zu Beta erweitert die Verfügbarkeit, macht den Vertrag aber noch nicht stabil.

## Verfügbarkeit und Berechtigungen

„Allgemein verfügbar“ bedeutet nicht uneingeschränkten Zugriff. Authentifizierung, Scopes, Mitglieds- und Projektberechtigungen gelten weiterhin. Siehe [Authentifizierung und Scopes](/docs/authentication).

Ein Closed-beta-Endpunkt kann bereits dokumentiert sein, obwohl er für deine Organisation noch nicht freigeschaltet ist. Ein neuer API-Key oder zusätzliche Scopes schalten die Funktion nicht frei. Eine ansonsten berechtigte Anfrage an eine gesperrte Funktion liefert HTTP `403` mit `FEATURE_UNAVAILABLE`; das Fehlerfeld `availability` nennt Ressource und Phase. Fehlende Zugangsdaten oder Berechtigungen können bereits vor der Freischaltungsprüfung zur Ablehnung führen.

## MCP-Tools

Für MCP-Tools gelten dieselben Stabilitätsgrundsätze wie für die zugrunde liegenden API-Operationen. Beschreibungen und Metadaten kennzeichnen `closed-beta`- und `beta`-Tools. Closed-beta-Tools werden nur freigeschalteten Organisationen angeboten; jeder Aufruf prüft den Zugriff erneut.

Die MCP-Protokollversion beschreibt die Kommunikation zwischen Client und Server. Sie ist unabhängig von der REST-API-Version und legt die Eingaben oder das Verhalten eines Beta-Tools nicht dauerhaft fest. Verbindungsdetails findest du im [MCP-Leitfaden](/docs/mcp).