Zum Hauptinhalt springen

API-Versionierung

Die neuroflash API verwendet URL-Pfad-Versionierung. Alle Endpoints enthalten ein Versionspräfix in ihrem Pfad.

Aktuelle Version​

Die API wird nicht als Ganzes versioniert. Stattdessen verwaltet jeder Service seine eigene Version unabhängig. Endpoints folgen dem Muster:

https://app.neuroflash.com/api/{service}/v1/{resource}

Jeder Service kann seine Version unabhängig erhöhen, wenn brechende Änderungen eingeführt werden — so könnte ein Service bereits auf v2 sein, während andere auf v1 bleiben.

Abwärtskompatibilität​

Wir betrachten die folgenden Änderungen als nicht-brechend und können sie ohne Versionserhöhung vornehmen:

  • Hinzufügen neuer API-Endpoints
  • Hinzufügen neuer optionaler Anfrageparameter
  • Hinzufügen neuer Felder zu Antwortobjekten
  • Hinzufügen neuer Enum-Werte
  • Hinzufügen neuer Fehlercodes
  • Ändern der Reihenfolge von Feldern in Antworten

Wir betrachten die folgenden Änderungen als brechend und werden eine neue Version einführen:

  • Entfernen oder Umbenennen bestehender Endpoints
  • Entfernen oder Umbenennen bestehender Antwortfelder
  • Ändern des Typs eines bestehenden Feldes
  • Umwandlung eines bisher optionalen Parameters in einen Pflichtparameter
  • Ändern der Bedeutung eines bestehenden Feldes oder Parameters
tipp

Gestalten Sie Ihre Integration so, dass sie unbekannte Felder fehlerfrei verarbeitet. Verwenden Sie tolerantes JSON-Parsing und vermeiden Sie strikte Schema-Validierung bei Antworten, damit Ihr Code weiterhin funktioniert, wenn neue Felder hinzugefügt werden.

Wie brechende Änderungen kommuniziert werden​

Wenn eine brechende Änderung notwendig ist, werden wir:

  1. Die neue Version unter einem neuen Pfad-Präfix veröffentlichen (z.B. /v2/)
  2. Die Änderung in unserer Dokumentation und im Changelog ankündigen
  3. Die vorherige Version für einen angemessenen Migrationszeitraum weiter unterstützen
  4. Einen Migrationsleitfaden für die neue Version bereitstellen