Informationen zur API-Versionsverwaltung
Die GitHub-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.
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.