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.