Schema
auf die API wird über http(s)://HOSTNAME/api/v3
zugegriffen. Alle Daten werden im JSON-Format gesendet und empfangen.
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/users/octocat/orgs
> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> X-GitHub-Enterprise-Version: 3.6.0
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff
Leere Felder werden mit null
angegeben anstatt ausgelassen zu werden.
Alle Zeitstempel werden im UTC-Zeitformat im ISO 8601-Format zurückgegeben:
YYYY-MM-DDTHH:MM:SSZ
Weitere Informationen zu Zeitzonen in Zeitstempeln findest du in diesem Abschnitt.
Zusammenfassungsdarstellungen
Wenn du eine Liste von Ressourcen abrufst, enthält die Antwort eine Teilmenge der Attribute für diese Ressource. Dies ist die „Zusammenfassungsdarstellung“ der Ressource. (Einige Attribute sind für die zu bereitstellende API berechnungsintensiv. Aus Leistungsgründen schließt die Zusammenfassungsdarstellung diese Attribute aus. Um diese Attribute abzurufen, ruf die „detaillierte“ Darstellung ab.)
Beispiel: Wenn du eine Liste von Repositorys erhältst, erhältst du die Zusammenfassungsdarstellung jedes Repositorys. Hier wird die Liste der Repositorys abgerufen, die der Organisation octokit gehört:
GET /orgs/octokit/repos
Detaillierte Darstellungen
Wenn du eine einzelne Ressource abrufst, enthält die Antwort normalerweise alle Attribute für diese Ressource. Dies ist die „detaillierte“ Darstellung der Ressource. (Beachte, dass die Autorisierung manchmal die Anzahl der Details in der Darstellung beeinflusst.)
Beispiel: Wenn du ein einzelnes Repository erhältst, erhältst du die detaillierte Darstellung des Repositorys. Hier rufst du das Repository octokit/octokit.rb ab:
GET /repos/octokit/octokit.rb
Die Dokumentation enthält eine Beispielantwort für jede API-Methode. Die Beispielantwort zeigt alle Attribute an, die von dieser Methode zurückgegeben werden.
Authentifizierung
GitHub empfiehlt die Erstellung eines Tokens zur Authentifizierung bei der REST-API. Weitere Informationen zum zu erstellenden Tokentyp findest du unter Authentifizieren bei der REST-API.
Du kannst deine Anforderung authentifizieren, indem du ein Token im Authorization
-Header deiner Anforderung sendest:
curl --request GET \
--url "http(s)://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"
Hinweis: In den meisten Fällen kannst du Authorization: Bearer
oder Authorization: token
verwenden, um ein Token zu übergeben. Wenn du jedoch ein JWT (JSON Web Token) übergibst, musst du Authorization: Bearer
verwenden.
Wenn du versuchst, einen REST-API-Endpunkt ohne ein Token oder mit einem Token zu verwenden, das über unzureichende Berechtigungen verfügt, wird die Meldung 404 Not Found
oder 403 Forbidden
zurückgegeben.
OAuth2-Schlüssel bzw. -Geheimnis
Veraltungshinweis: GitHub führt die Authentifizierung mit der API mit Abfrageparametern nicht mehr aus. Die Authentifizierung mit der API sollte mit HTTP-Standardauthentifizierung erfolgen. Weitere Informationen (einschließlich geplanter Änderungen) findest du im Blogbeitrag.
Die Authentifizierung bei der API mithilfe von Abfrageparametern (wenn verfügbar) wird aufgrund von Sicherheitsbedenken nicht mehr unterstützt. Stattdessen wird empfohlen, dass Integratoren ihr Zugriffstoken (client_id
) oder das client_secret
in die Kopfzeile verschieben. GitHub wird die Abschaffung der Authentifizierung durch Abfrageparameter mit einer Vorankündigung ankündigen.
curl -u my_client_id:my_client_secret 'http(s)://<em>HOSTNAME</em>/api/v3/user/repos'
Wenn du client_id
und client_secret
verwendest, wirst du nicht als Benutzerin authentifiziert. Stattdessen wird nur deine OAuth app identifiziert, um deine Ratenbegrenzung zu erhöhen. Berechtigungen werden nur Benutzerinnen und keinen Anwendungen gewährt. Zudem erhältst du nur Daten, die nicht authentifizierte Benutzerinnen sehen würden. Veröffentliche den geheimen Clientschlüssel deiner OAuth app nicht für deine Benutzerinnen.
Im privaten Modus kannst du dich nicht mit deinem OAuth2-Schlüssel bzw. -Geheimnis authentifizieren, und bei einem Authentifizierungsversuch wird 401 Unauthorized
zurückgegeben. Weitere Informationen findest du unter Privaten Modus aktivieren.
Grenzwert für fehlgeschlagene Anmeldeversuche
Bei der Authentifizierung mit ungültigen Anmeldeinformationen wird 401 Unauthorized
zurückgegeben:
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401
> {
> "message": "Bad credentials",
> "documentation_url": "https://docs.github.com/enterprise/3.6/rest"
> }
Nach der Erkennung mehrerer Anforderungen mit ungültigen Anmeldeinformationen innerhalb eines kurzen Zeitraums lehnt die API vorübergehend alle Authentifizierungsversuche für diesen Benutzerin (auch Benutzer*innen mit gültigen Anmeldeinformationen) mit der Fehlermeldung 403 Forbidden
ab:
> HTTP/2 403
> {
> "message": "Maximum number of login attempts exceeded. Please try again later.",
> "documentation_url": "https://docs.github.com/enterprise/3.6/rest"
> }
Parameter
Viele API-Methoden verwenden optionale Parameter. Für GET
-Anforderungen können alle Parameter, die nicht als Segment im Pfad angegeben werden, als HTTP-Abfragezeichenfolgenparameter übergeben werden:
curl -i "http(s)://<em>HOSTNAME</em>/api/v3/repos/vmg/redcarpet/issues?state=closed"
In diesem Beispiel werden die Werte „vmg“ und „redcarpet“ für die Parameter :owner
und :repo
im Pfad angegeben, während :state
in der Abfragezeichenfolge übergeben wird.
Für die Anforderungen POST
, PATCH
, PUT
und DELETE
sollten Parameter, die nicht in der URL enthalten sind, als JSON mit einem Inhaltstyp von „application/json“ codiert werden:
curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' http(s)://<em>HOSTNAME</em>/api/v3/authorizations
Stammendpunkt
Du kannst eine GET
-Anforderung an den Stammendpunkt stellen, um alle Endpunktkategorien abzurufen, die die REST-API unterstützt:
$ curl -u USERNAME:PASSWORD http(s)://<em>HOSTNAME</em>/api/v3
Globale GraphQL-Knoten-IDs
Im Leitfaden zu Verwenden globaler Knoten-IDs findest du detaillierte Informationen darüber, wie du node_id
s über die REST-API suchen kannst und in GraphQL-Vorgängen verwendest.
Clientfehler
Es gibt drei mögliche Arten von Clientfehlern bei API-Aufrufen, die Anforderungstexte erhalten:
-
Das Senden ungültiger JSON-Daten führt zu einer
400 Bad Request
-Antwort.HTTP/2 400 Content-Length: 35 {"message":"Problems parsing JSON"}
-
Das Senden des falschen Typs von JSON-Werten führt zu einer
400 Bad Request
-Antwort.HTTP/2 400 Content-Length: 40 {"message":"Body should be a JSON object"}
-
Das Senden ungültiger Felder führt zu einer
422 Unprocessable Entity
-Antwort.HTTP/2 422 Content-Length: 149 { "message": "Validation Failed", "errors": [ { "resource": "Issue", "field": "title", "code": "missing_field" } ] }
Alle Fehlerobjekte verfügen über Ressourcen- und Feldeigenschaften, damit dein Client genauere Angaben zum Problem machen kann. Es gibt auch einen Fehlercode, um Ihnen mitzuteilen, welches Problem im Zusammenhang mit dem Feld vorliegt.
Fehlercode | BESCHREIBUNG |
---|---|
missing | Eine Ressource ist nicht vorhanden. |
missing_field | Ein erforderliches Feld für eine Ressource wurde nicht festgelegt. |
invalid | Die Formatierung eines Felds ist ungültig. Weitere spezifische Informationen findest du in der Dokumentation. |
already_exists | Eine andere Ressource hat den gleichen Wert wie dieses Feld. Dies kann bei Ressourcen der Fall sein, die einen eindeutigen Schlüssel haben müssen (z. B. Bezeichnungsnamen). |
unprocessable | Die bereitgestellten Eingaben waren ungültig. |
Ressourcen können auch benutzerdefinierte Überprüfungsfehler senden (wobei code
custom
entspricht). Benutzerdefinierte Fehler enthalten immer ein message
-Feld, in dem der Fehler beschrieben wird. Die meisten Fehler umfassen zudem ein documentation_url
-Feld, in dem auf Inhalte verwiesen wird, die beim Beheben des Fehlers helfen können.
HTTP-Umleitungen
Die GitHub Enterprise Server-REST-API verwendet ggf. die HTTP-Umleitung. Clients sollten davon ausgehen, dass jede Anforderung zu einer Umleitung führen kann. Der Empfang einer HTTP-Umleitung ist kein Fehler, und Clients sollten dieser Umleitung folgen. Umleitungsantworten verfügen über ein Location
-Headerfeld, das den URI der Ressource enthält, für die der Client die Anforderungen wiederholen sollte.
Ein 301
-Statuscode steht für eine permanente Umleitung. Der URI, den du zum Erstellen der Anforderung verwendet hast, wurde durch den im Location
-Headerfeld angegebenen URI ersetzt. Diese und alle zukünftigen Anforderungen an diese Ressource sollten an den neuen URI weitergeleitet werden.
Ein 302
- oder 307
-Statuscode steht für eine temporäre Umleitung. Die Anforderung sollte für den im Location
-Headerfeld angegebenen URI unverändert wiederholt werden, aber die Clients sollten weiterhin den ursprünglichen URI für zukünftige Anforderungen verwenden.
Andere Umleitungsstatuscodes können gemäß der HTTP 1.1-Spezifikation verwendet werden.
HTTP-Verben
Sofern möglich, bemüht sich die GitHub Enterprise Server-REST-API, geeignete HTTP-Verben für jede Aktion zu verwenden. Bei HTTP-Verben muss Groß-/Kleinschreibung beachtet werden.
Verb | BESCHREIBUNG |
---|---|
HEAD | Kann für jede Ressource ausgestellt werden, um nur die HTTP-Headerinformationen abzurufen. |
GET | Wird zum Abrufen von Ressourcen verwendet. |
POST | Wird zum Erstellen von Ressourcen verwendet. |
PATCH | Wird zum Aktualisieren von Ressourcen mit teilweisen JSON-Daten verwendet. Beispielsweise verfügt eine Issue-Ressource über die Attribute title und body . Eine PATCH -Anforderung kann eines oder mehrere der Attribute akzeptieren, um die Ressource zu aktualisieren. |
PUT | Wird zum Ersetzen von Ressourcen oder Sammlungen verwendet. Stelle für PUT -Anforderungen ohne body -Attribut sicher, dass der Content-Length -Header auf null (0) festgelegt wird. |
DELETE | Wird zum Löschen von Ressourcen verwendet. |
Hypermedia
Alle Ressourcen verfügen möglicherweise über eine oder mehrere *_url
-Eigenschaften, die sie mit anderen Ressourcen verknüpfen. Hiermit sollen explizite URLs bereitgestellt werden, damit richtige API-Clients keine URLs selbst erstellen müssen. Es wird dringend empfohlen, dass API-Clients diese verwenden. Auf diese Weise werden zukünftige Upgrades der API für Entwickler*innen einfacher. Es wird erwartet, dass alle URLs ordnungsgemäße RFC 6570-URI-Vorlagen sind.
Anschließend kannst du diese Vorlagen mithilfe des uri_template-Gems erweitern:
>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"
>> tmpl.expand all: 1
=> "/notifications?all=1"
>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"
Paginierung
Wenn eine Antwort der REST-API viele Ergebnisse enthält, werden die Ergebnisse von GitHub paginiert, und es wird eine Teilmenge der Ergebnisse zurückgegeben. Du kannst den Linkheader aus der Antwort verwenden, um zusätzliche Datenseiten anzufordern. Wenn ein Endpunkt den Abfrageparameter per_page
unterstützt, kannst du steuern, wie viele Ergebnisse auf einer Seite zurückgegeben werden. Weitere Informationen zur Paginierung findest du unter Verwenden der Paginierung in der REST-API.
Zeitlimits
Wenn die Verarbeitung einer API-Anforderung durch GitHub länger als zehn Sekunden dauert, wird die Anforderung durch GitHub beendet, und du erhältst eine Timeoutantwort wie die folgende:
{
"message": "Server Error"
}
GitHub Enterprise Server behält sich das Recht vor, das Timeoutfenster zu ändern, um die Geschwindigkeit und Zuverlässigkeit der API zu schützen.
Ratenbegrenzung
Die GitHub Enterprise Server-REST-API verwendet Ratenlimits, um den API-Datenverkehr zu steuern. Unterschiedliche Arten von API-Anforderungen haben verschiedene Ratenbegrenzungen. Die Antwortheader beschreiben deinen aktuellen Ratenbegrenzungsstatus.
Ratenbegrenzungen
Die unterschiedlichen Arten von API-Anforderungen an deine GitHub Enterprise Server-Instanz unterliegen unterschiedlichen Ratenbegrenzungen. Darüber hinaus weisen die Suchendpunkte dedizierte Grenzwerte auf. Weitere Informationen findest du in der REST-API-Dokumentation unter Suchen,.
Für GitHub Enterprise Server sind Ratenbegrenzungen standardmäßig deaktiviert. Wende dich an deine Websiteadministrator*innen, um die Ratenlimits für deine Instanz zu bestätigen.
Ratenbegrenzungen für Anforderungen von persönlichen Konten
Du kannst direkte API-Anforderungen senden, die du mit einem personal access token authentifizierst. Eine OAuth app oder GitHub App kann auch eine Anforderung in deinem Namen senden, nachdem du die App autorisiert hast. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken, Autorisieren von OAuth-Apps und Autorisieren von GitHub-Apps.
GitHub Enterprise Server ordnet den authentifizierten Benutzerinnen alle Anforderungen zu. Bei OAuth apps und GitHub Apps handelt es sich um den oder die Benutzerin, der oder die die App autorisiert. Alle diese Anforderungen werden zur Ratenbegrenzung der authentifizierten Benutzer*innen hinzugezählt.
Anforderungen für Benutzerzugriffstoken sind standardmäßig auf 5.000 Anforderungen pro Stunde und pro authentifiziertem Benutzer/authentifizierter Benutzerin beschränkt. Alle Anfragen von OAuth apps, die von einem Benutzer oder einem personal access token, der dem Benutzer gehört, autorisiert wurden, und Anfragen, die mit einem der Authentifizierungsnachweise des Benutzers authentifiziert wurden, teilen sich das gleiche Kontingent von Anfragen pro Stunde für diesen Benutzer.
Ratenbegrenzungen für Anforderungen von GitHub Apps
Anforderungen von einer GitHub App können entweder ein Benutzerzugriffstoken oder ein Installationszugriffstoken verwenden. Weitere Informationen zu Ratenbegrenzungen für GitHub Apps findest du unter Rate limits for GitHub Apps (Ratenbegrenzungen für GitHub-Apps).
Ratenbegrenzungen für Anforderungen von GitHub Actions
Du kannst das integrierte GITHUB_TOKEN
verwenden, um Anforderungen in GitHub Actions-Workflows zu authentifizieren. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.
Bei Verwendung von GITHUB_TOKEN
beträgt die Ratenbegrenzung 1.000 Anforderungen pro Stunde und Repository.
Überprüfen des Status der Ratenbegrenzung
Die Antwortheader beschreiben deinen aktuellen Ratenbegrenzungsstatus. Du kannst auch die REST-API verwenden, um die aktuelle Anzahl von API-Aufrufen zu ermitteln, die dir oder deiner App jederzeit zur Verfügung stehen.
Ratenbegrenzungsheader
Der Antwortheader x-ratelimit
beschreibt den aktuellen Ratenbegrenzungsstatus nach jeder Anforderung:
$ curl -i http(s)://<em>HOSTNAME</em>/api/v3/users/octocat
> HTTP/2 200
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 56
> x-ratelimit-used: 4
> x-ratelimit-reset: 1372700873
Headername | BESCHREIBUNG |
---|---|
x-ratelimit-limit | Die maximale Anzahl von Anforderungen, die du pro Stunde stellen darfst. |
x-ratelimit-remaining | Die Anzahl der Anforderungen, die im aktuellen Ratenbegrenzungsfenster verbleiben. |
x-ratelimit-used | Die Anzahl der Anforderungen, die du im aktuellen Ratenbegrenzungsfenster gesendet hast |
x-ratelimit-reset | Die Zeit in Sekunden seit der UTC-Epoche, zu der das aktuelle Ratenbegrenzungsfenster zurückgesetzt wird. |
Überprüfen des Ratenbegrenzungsstatus mit der REST-API
Du kannst die REST-API verwenden, um den Ratenbegrenzungsstatus zu überprüfen, ohne dass diese Anforderung zur aktuellen Begrenzung hinzugezählt wird. Weitere Informationen findest du unter Rate Limit. GitHub empfiehlt nach Möglichkeit stattdessen die Verwendung des Antwortheaders x-ratelimit
, um die Auslastung der API zu verringern.
Überschreiten der Ratenbegrenzung
Wenn du die Ratenbegrenzung überschreitest, weist die Antwort den 403
-Status auf, und der x-ratelimit-remaining
-Header entspricht 0
:
> HTTP/2 403
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 0
> x-ratelimit-used: 60
> x-ratelimit-reset: 1377013266
> {
> "message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
> "documentation_url": "https://docs.github.com/enterprise/3.6/rest/overview/resources-in-the-rest-api#rate-limiting"
> }
Bei einer Ratenbegrenzung sollte erst nach Erreichen der durch x-ratelimit-reset
festgelegten Zeit eine Anforderung übermittelt werden.
Erhöhen der Begrenzung für nicht authentifizierte Raten für OAuth apps
Wenn deine OAuth app nicht authentifizierte Aufrufe von öffentlichen Ressourcen mit einer höheren Ratenbegrenzung senden muss, kannst du die Client-ID und den geheimen Schlüssel deiner App vor der Endpunktroute übergeben.
$ curl -u my_client_id:my_client_secret -I http(s)://<em>HOSTNAME</em>/api/v3/meta
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4966
> x-ratelimit-used: 34
> x-ratelimit-reset: 1372700873
Hinweis: Teile deinen geheimen Clientschlüssel niemals mit anderen Personen, und füge ihn nicht in clientseitigen Browsercode ein.
Einhalten der Ratenbegrenzung
Wenn du bei Verwendung der Standardauthentifizierung oder OAuth die Ratenbegrenzung überschreitest, kannst du das Problem wahrscheinlich beheben, indem du API-Antworten zwischenspeicherst und bedingte Anforderungen verwendest.
Sekundäre Ratenbegrenzungen
Die zuvor beschriebenen Ratenbegrenzungen gelten für die gesamte REST-API sowie pro Benutzer*in oder pro App. Um den Qualitätsdienst für GitHub Enterprise Server bereitzustellen, gelten bei Verwendung der API möglicherweise zusätzliche Ratenbegrenzungen für einige Aktionen. Wenn du beispielsweise die API verwendest, um schnell Inhalte zu erstellen, du anstelle der Verwendung von Webhooks offensiv abfragst, mehrere gleichzeitige Anforderungen stellst oder wiederholt berechnungsintensive Daten anforderst, kann dies zu einer zusätzlichen Ratenbegrenzung führen.
Diese zusätzlichen Ratenbegrenzungen sollen nicht die legitime Verwendung der API beeinträchtigen. Deine normalen Ratenbegrenzungen sollten die einzige Grenze sein, die du erreichst. Lies die Anleitung mit bewährten Methoden, um sicherzustellen, dass du die API ordnungsgemäß verwendest.
Wenn deine Anwendung eine zusätzliche Ratenbegrenzung auslöst, erhältst du eine informative Antwort:
> HTTP/2 403
> Content-Type: application/json; charset=utf-8
> Connection: close
> {
> "message": "You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later.",
> "documentation_url": "https://docs.github.com/enterprise/3.6/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }
Du solltest warten und die Anforderung zu einem späteren Zeitpunkt erneut versuchen. Wenn der Antwortheader retry-after
vorhanden ist, solltest du deine Anforderung erst nach Ablauf dieser Sekundenzahl erneut übermitteln. Wenn der x-ratelimit-remaining
-Header 0
lautet, solltest du die Anforderung erst nach Ablauf der im x-ratelimit-reset
-Header angegebenen UTC-Epochensekunden erneut senden. Lass andernfalls eine exponentiell länger werdende Zeitspanne zwischen den Wiederholungsversuchen verstreichen und gib nach einer bestimmten Anzahl von Wiederholungsversuchen einen Fehler aus.
Bedingte Anforderungen
Die meisten Antworten geben einen ETag
-Header zurück. Viele Antworten geben auch einen Last-Modified
-Header zurück. Du kannst die Werte dieser Header verwenden, um mithilfe der Header If-None-Match
bzw. If-Modified-Since
nachfolgende Anforderungen an diese Ressourcen zu stellen. Wenn die Ressource nicht geändert wurde, gibt der Server 304 Not Modified
zurück.
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/user
> HTTP/2 200
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
> HTTP/2 304
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
> HTTP/2 304
> Cache-Control: private, max-age=60
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873
Cross-Origin Resource Sharing
Die API unterstützt CORS (Cross-Origin Resource Sharing) für AJAX-Anforderungen aus jedem Ursprung. Du kannst die CORS-W3C-Empfehlung oder diese Einführung im HTML 5-Sicherheitsleitfaden lesen.
Im Folgenden findest du eine Beispielanforderung, die von einem Browser gesendet wird, der http://example.com
aufruft:
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Die CORS-Preflight-Anforderung lautet wie folgt:
$ curl -I http(s)://<em>HOSTNAME</em>/api/v3 -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400
JSON-P-Rückrufe
Du kannst einen ?callback
-Parameter an einen beliebigen GET-Aufruf senden, um die Ergebnisse in einer JSON-Funktion zu umschließen. Dieser Ansatz wird in der Regel verwendet, wenn Browser GitHub Enterprise Server-Inhalte in Webseiten einbetten möchten, indem domänenübergreifende Probleme umgangen werden. Die Antwort enthält die gleiche Datenausgabe wie die reguläre API sowie die relevanten HTTP-Headerinformationen.
$ curl http(s)://<em>HOSTNAME</em>/api/v3?callback=foo
> /**/foo({
> "meta": {
> "status": 200,
> "x-ratelimit-limit": "5000",
> "x-ratelimit-remaining": "4966",
> "x-ratelimit-reset": "1372700873",
> "Link": [ // pagination headers and other links
> ["http(s)://<em>HOSTNAME</em>/api/v3?page=2", {"rel": "next"}]
> ]
> },
> "data": {
> // the data
> }
> })
Du kannst einen JavaScript-Handler schreiben, um den Rückruf zu verarbeiten. Hier findest du ein minimales Beispiel, das du ausprobieren kannst:
<html>
<head>
<script type="text/javascript">
function foo(response) {
var meta = response.meta;
var data = response.data;
console.log(meta);
console.log(data);
}
var script = document.createElement('script');
script.src = 'http(s)://HOSTNAME/api/v3?callback=foo';
document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>
<body>
<p>Open up your browser's console.</p>
</body>
</html>
Alle Header haben den gleichen Zeichenfolgenwert wie die HTTP-Header mit einer wichtigen Ausnahme: Link. Link-Header werden vorab für dich analysiert und als Array von [url, options]
-Tupeln angezeigt.
Ein Link wie der folgende ...
Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"
... sieht in der Rückrufausgabe wie folgt aus:
{
"Link": [
[
"url1",
{
"rel": "next"
}
],
[
"url2",
{
"rel": "foo",
"bar": "baz"
}
]
]
}
Zeitzonen
Einige Anforderungen, die neue Daten erstellen (z. B. das Erstellen eines neuen Commits), ermöglichen es dir, Zeitzoneninformationen bereitzustellen, wenn du Zeitstempel angibst oder generierst. Du wendest die folgenden Regeln in der Reihenfolge ihrer Priorität an, um Zeitzoneninformationen für solche API-Aufrufe zu ermitteln.
- Explizites Bereitstellen eines ISO 8601-Zeitstempels mit Zeitzoneninformationen
- Verwenden des
Time-Zone
-Headers - Verwenden der letzten bekannten Zeitzone für Benutzer*innen
- Standardmäßiges Festlegen auf UTC ohne andere Zeitzoneninformationen
Beachte, dass diese Regeln nur für Daten gelten, die an die API übergeben werden, und nicht für Daten, die von der API zurückgegeben werden. Wie unter Schema erwähnt liegen von der API zurückgegebene Zeitstempel im UTC-Zeitformat gemäß ISO 8601 vor.
Explizites Bereitstellen eines ISO 8601-Zeitstempels mit Zeitzoneninformationen
API-Aufrufe, die das Angeben eines Zeitstempels ermöglichen, wird dieser genaue Zeitstempel verwendet. Ein Beispiel hierfür ist die API zum Verwalten von Commits. Weitere Informationen findest du unter Git-Datenbank.
Diese Zeitstempel sehen in etwa wie 2014-02-27T15:05:06+01:00
aus. In diesem Beispiel wird gezeigt, wie diese Zeitstempel angegeben werden können.
Verwenden des Time-Zone
-Headers
Es ist möglich, einen Time-Zone
-Header zu geben, der eine Zeitzone gemäß der Liste der Namen aus der Olson-Datenbank definiert.
curl -H "Time-Zone: Europe/Amsterdam" -X POST http(s)://<em>HOSTNAME</em>/api/v3/repos/github-linguist/linguist/contents/new_file.md
Dies bedeutet, dass du einen Zeitstempel für den Zeitpunkt generierst, zu dem dein API-Aufruf in der Zeitzone erfolgt, die dieser Header definiert. Die API zum Verwalten von Inhalten generiert beispielsweise einen Git-Commit für jede Ergänzung oder Änderung und verwendet die aktuelle Uhrzeit als Zeitstempel. Weitere Informationen findest du unter Repositorys. Dieser Header bestimmt die Zeitzone, die zum Generieren dieses aktuellen Zeitstempels verwendet wird.
Verwenden der letzten bekannten Zeitzone für Benutzer*innen
Wenn kein Time-Zone
-Header angegeben ist und du einen authentifizierten Aufruf der API vornimmst, verwende die letzte bekannte Zeitzone für die authentifizierten Benutzer*innen. Die letzte bekannte Zeitzone wird aktualisiert, wenn du die GitHub Enterprise Server-Website durchsuchst.
Standardmäßiges Festlegen auf UTC ohne andere Zeitzoneninformationen
Wenn die obigen Schritte keine Informationen bereitstellen, verwende UTC als Zeitzone, um den Git-Commit zu erstellen.