API-Versionierung und Deprecation

Die Endless-REST-API unter https://api.endless.app wird über einen Request-Header versioniert, nicht über die URL. Aktuell ist nichts deprecated.

Version festlegenLink kopieren

Die aktuelle Version ist 1.0.0. Pfade haben kein Versionssegment (/assets, nicht /v1/assets).

Endless-Api-Version: 1

• Nur die Hauptversion zählt: 1 und 1.0.0 bedeuten dasselbe.
• Ohne den Header akzeptierst du die aktuelle Version.
• Jede Antwort trägt Endless-Api-Version mit der Version, die sie geliefert hat.
• Eine Hauptversion, die die API nicht bedienen kann, scheitert mit 400 und unsupported_api_version:

{
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "This deployment serves API version 1.0.0; the request asked for 2.",
  "data": {
    "code": "unsupported_api_version",
    "hint": "Send `Endless-Api-Version: 1`, or omit the header to accept the current version.",
    "documentation": "https://endless.app/docs/api"
  }
}

Was sich innerhalb einer Hauptversion ändertLink kopieren

Nur Ergänzungen: neue Operationen, neue optionale Eingaben, neue Felder in Antworten. Ignoriere Antwortfelder, die du nicht kennst. Eine Operation oder ein Feld zu entfernen oder den Typ eines Felds zu ändern, ist eine neue Hauptversion.

DeprecationLink kopieren

Eine veraltete Operation funktioniert mindestens 180 Tage weiter, nachdem ihr erster Deprecation-Header ausgeliefert wurde, und ihr Sunset-Datum liegt nie früher. Jede Antwort von ihr trägt diese Signale:

Maschinenlesbare QuellenLink kopieren

• OpenAPI-Dokument: info.description beschreibt diese Policy, info.version ist die aktuelle Version.
• API-Index: Sein Objekt versioning listet den Header, die aktuelle Version, die unterstützten Hauptversionen und deprecation_notice_days.
• API-Referenz: jede Operation, generiert aus dem OpenAPI-Dokument.