Ressourcen in der REST-API

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.7.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"

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

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.7/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.7/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_ids über die REST-API suchen kannst und in GraphQL-Vorgängen verwendest.

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"

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.