App öffnen
Moonborn — Developers

API-Versionierungs-Policy

Wie Moonborn die API versioniert, Deprecation-Timelines, Breaking-Change-Notice-Windows und was als Breaking-Change vs. Additive zählt.

Moonborns API nutzt Path-Segment-Versioning: jeder Endpoint lebt unter /v1/ (oder /v2/, sobald wir es versenden). Die Version ist Teil der URL, sodass Clients explizit pinnen und Migrationen absichtlich sind.

Versionen

  • v1 — Aktuell. General Availability. Stabile Kontrakte.
  • v2 — Noch nicht released. Wenn es versendet wird, tritt v1 in ein Deprecation-Window (siehe unten).

Was als Breaking-Change zählt

Änderungen, die eine neue Version erfordern:

  • Umbenennen eines Felds in einer Response.
  • Entfernen eines Felds aus einer Response.
  • Ändern des Typs oder der Form eines Response-Felds.
  • Hinzufügen eines neuen Pflichtfelds zu einem Request.
  • Umbenennen oder Entfernen eines Endpoints.
  • Ändern der Auth-Anforderungen eines Endpoints (z. B. einen neuen Scope erfordern).
  • Ändern der Bedeutung eines Enum-Werts, der bereits in Nutzung ist.

Änderungen, die additive sind (ohne Version-Bump versenden):

  • Hinzufügen optionaler Request-Felder mit vertretbaren Defaults.
  • Hinzufügen neuer Response-Felder (Clients ignorieren unbekannte Felder).
  • Hinzufügen neuer Endpoints.
  • Hinzufügen neuer Enum-Werte zu Request-Feldern (Clients senden, was sie kennen; neue Werte werden akzeptiert).
  • Hinzufügen neuer Error-Codes (Clients sollten unbekannte Codes default-handlen).
  • Hinzufügen neuer Webhook-Event-Typen.
  • Hinzufügen neuer tier-gated Features (Free-Clients sehen die existierende Form; Pro/Team/Enterprise-Clients sehen neue Felder).

Enum-Hinzufügungen in Response-Feldern sind technisch breaking — ein Client, der exhaustive pattern-matched, fällt durch. Wir dokumentieren sie mit einem Release-Notes-Callout und migrieren graduell.

Deprecation-Timeline

Wenn v2 versendet wird:

  • Tag 0: v2 GA. v1 serviert weiter Traffic.
  • Tag 0 + 6 Monate: v1 als deprecated markiert. Response-Header tragen Deprecation: true und Sunset: <Datum>.
  • Tag 0 + 12 Monate: v1 entfernt. Clients, gepinnt auf /v1/, bekommen 410 Gone mit einem Migration-Pointer-Envelope.

Sechs Monate sind der Boden; speziell für v1 (die initiale Version) wird das Deprecation-Window mindestens 12 Monate sein. Zukünftige Version-Bumps folgen dem 6-Monats-Boden, außer eine Security-Forcing- Function greift ein.

Die Version lesen

curl https://api.moonborn.co/v1/version

Gibt zurück:

{
  "apiVersion": "1.0.0",
  "buildSha": "...",
  "deployedAt": "2026-05-16T08:00:00Z"
}

apiVersion folgt Semver. Major-Bumps sind Path-Version-Wechsel (v1 → v2). Minor- + Patch-Bumps bleiben innerhalb desselben Paths.

SDK-Alignment

Jedes SDK-Release ist auf eine API-Minor-Version gepinnt. SDK 1.4.x spricht API 1.4.*; SDK 2.0.x spricht API 2.x. Das SDK weigert sich, gegen einen Path-Version-Mismatch zu starten.

OpenAPI-Spec

/openapi.json reflektiert immer die aktuelle deployed Spec. Baue deine eigenen Clients daraus; pinne einen Snapshot in deinem Repo, wenn du reproducible Builds willst. CI hält apps/api/openapi.json und apps/docs/public/openapi.json byte-identisch.

Ehrlicher Scope

Wir pflegen nicht mehrere Minor-Versionen gleichzeitig. Es gibt keinen Weg, v1.3 der API anzufragen, wenn v1.4 versendet wurde — Minor-Bumps sind nur additive, also sind v1.3 und v1.4 aus der Client-POV wire-kompatibel.

Die Major-Version ist die Vertragseinheit. Pinne auf v1; migriere, wenn das Deprecation-Window öffnet; nicht davor.

Weiter