Skip to main content

API-Versionen

Bei jeder Anforderung an die REST-API müssen Sie angeben, welche Version der REST-API verwendet werden soll.

Informationen zur API-Versionsverwaltung

Die GitHub Enterprise Server-REST-API ist versionsspezifisch. Der API-Versionsname basiert auf dem Datum, an dem die API-Version veröffentlicht wurde. Beispielsweise wurde die API-Version 2022-11-28 am Mon, 28 Nov 2022 veröffentlicht.

Alle Breaking Changes werden in einer neuen API-Version veröffentlicht. Breaking Changes sind Änderungen, die möglicherweise eine Integration unterbrechen können. Zu Breaking Changes gehören:

  • Entfernen eines gesamten Vorgangs
  • Entfernen oder Umbenennen eines Parameters
  • Entfernen oder Umbenennen eines Antwortfelds
  • Hinzufügen eines neuen erforderlichen Parameters
  • Erforderlichmachen eines zuvor optionalen Parameters
  • Ändern des Typs eines Parameters oder Antwortfelds
  • Entfernen von Enumerationswerten
  • Hinzufügen einer neuen Validierungsregel zu einem vorhandenen Parameter
  • Ändern der Authentifizierungs- oder Autorisierungsanforderungen

Alle additiven (Nonbreaking) Changes sind in allen unterstützten API-Versionen verfügbar. Additive Änderungen sind Änderungen, die eine Integration nicht unterbrechen sollten. Zu den additiven Änderungen gehören:

  • Hinzufügen eines Vorgangs
  • Hinzufügen eines optionalen Parameters
  • Hinzufügen eines optionalen Anforderungsheaders
  • Hinzufügen eines Antwortfelds
  • Hinzufügen eines Antwortheaders
  • Hinzufügen von Enumerationswerten

Wenn eine neue REST-API-Version veröffentlicht wird, wird die vorherige API-Version noch mindestens 24 Monate nach der Veröffentlichung der neuen API-Version unterstützt.

Informationen zur GitHub Enterprise Server-Versionsverwaltung und REST-API-Versionsverwaltung

GitHub Enterprise Server-Versionen sind von REST-API-Versionen entkoppelt. Du kannst ein Upgrade deiner GitHub Enterprise Server-Version durchführen, aber dieselbe REST-API-Version beibehalten, solange die API-Version in der GitHub Enterprise Server-Version enthalten ist. Ebenso kannst du ein Upgrade deiner REST-API-Version durchführen, ohne deine GitHub Enterprise Server-Version zu aktualisieren, solange die von dir ausgewählte neue REST-API-Version für deine GitHub Enterprise Server-Version verfügbar ist.

In den GitHub Enterprise Server-Versionshinweisen ist angegeben, wenn eine REST-API-Version nicht mehr unterstützt wird. Weitere Informationen findest du unter Versionshinweise.

Angeben einer API-Version

Du solltest den X-GitHub-Api-Version-Header verwenden, um eine API-Version anzugeben. Beispiel:

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

Anforderungen ohne X-GitHub-Api-Version-Header verwenden standardmäßig die Version 2022-11-28.

Wenn du eine API-Version angibst, die nicht mehr unterstützt wird, wird eine 400 Fehlermeldung angezeigt.

Upgrade auf eine neue API-Version

Bevor du ein Upgrade auf eine neue REST-API-Version durchführst, solltest du das Änderungsprotokoll der Breaking Changes lesen, um zu verstehen, welche Breaking Changes enthalten sind und um weitere Informationen über das Upgrade auf diese bestimmte API-Version zu erhalten. Weitere Informationen findest du unter Aktuelle Änderungen.

Wenn du deine Integration aktualisierst, um die neue API-Version im Header X-GitHub-Api-Version anzugeben, musst du auch alle erforderlichen Änderungen vornehmen, damit deine Integration mit der neuen API-Version funktioniert.

Sobald deine Integration aktualisiert ist, teste sie, um zu überprüfen, ob sie mit der neuen API-Version funktioniert.

Unterstützte API-Versionen

Die folgenden REST-API-Versionen werden derzeit unterstützt:

2022-11-28

Du kannst auch eine API-Anforderung stellen, um alle unterstützten API-Versionen abzurufen. Weitere Informationen findest du unter REST-API-Endpunkte für Metadaten.