Erste Schritte mit der REST-API

Einführung

Dieser Artikel beschreibt, wie du die GitHub-REST-API mit der GitHub CLI, curl oder JavaScript nutzen kannst. Für eine Schnellstartanleitung siehe Schnellstart für GitHub REST-API.

Informationen zu Anforderungen an die REST-API

In diesem Abschnitt werden die Elemente beschrieben, aus denen eine API-Anforderung besteht:

•         [HTTP-Methode](#http-method)
  

•         [Pfad](#path)
  

•         [Kopfzeilen](#headers)
  

•         [Medientypen](#media-types)
  

•         [Authentifizierung](#authentication)
  

•         [Parameter](#parameters)
  

Jede Anforderung an die REST-API enthält eine HTTP-Methode und einen Pfad. Je nach REST-API-Endpunkt müssen Sie möglicherweise auch Anforderungsheader, Authentifizierungsinformationen, Abfrageparameter oder Textparameter angeben.

Die REST-API-Referenzdokumentation beschreibt die HTTP-Methode, den Pfad und die Parameter für jeden Endpunkt. Außerdem werden für jeden Endpunkt Beispielanforderungen und -antworten bereitgestellt. Weitere Informationen finden Sie in der REST-Referenzdokumentation.

HTTP-Methode

Die HTTP-Methode eines Endpunkts definiert den Typ der Aktion, die er für eine bestimmte Ressource ausführt. Einige gängige HTTP-Methoden sind GET, POST, DELETE und PATCH. Die REST-API-Referenzdokumentation stellt die HTTP-Methode für jeden Endpunkt bereit.

Die HTTP-Methode für den Endpunkt „Repositoryprobleme auflisten“ lautet z. B. GET.“

Sofern möglich, bemüht sich die GitHub-REST-API, eine geeignete HTTP-Methode für jede Aktion zu verwenden.

•         `GET`: Wird zum Abrufen von Ressourcen verwendet.
  

•         `POST`: Wird zum Erstellen von Ressourcen verwendet.
  

•         `PATCH`: Wird zum Aktualisieren von Eigenschaften von Ressourcen verwendet.
  

•         `PUT`: Wird zum Ersetzen von Ressourcen oder Sammlungen von Ressourcen verwendet.
  

•         `DELETE`: Wird zum Löschen von Ressourcen verwendet.
  

Pfad

Jeder Endpunkt hat einen Pfad. Die REST-API-Referenzdokumentation gibt den Pfad für jeden Endpunkt an. Der Pfad zum Endpunkt „Repositoryprobleme auflisten“ lautet beispielsweise /repos/{owner}/{repo}/issues.

Die geschweiften Klammern {} in einem Pfad bezeichnen Pfadparameter, die Sie angeben müssen. Pfadparameter ändern den Endpunktpfad und sind in Ihrer Anforderung erforderlich. Die Pfadparameter zum Endpunkt „Repositoryprobleme auflisten“ lauten beispielsweise {owner} und {repo}. Wenn Sie diesen Pfad in Ihrer API-Anforderung verwenden möchten, ersetzen Sie {repo} mit dem Namen des Repositorys, für das Sie eine Liste von Issues anfordern möchten, und ersetzen Sie {owner} mit dem Namen des Kontos, das das Repository besitzt.

Header

Header enthalten zusätzliche Informationen zur Anforderung und zur gewünschten Antwort. Im Folgenden finden Sie einige Beispiele für Header, die Sie in Ihren Anforderungen an die GitHub REST-API verwenden können. Ein Beispiel für eine Anforderung, die Header verwendet, findest du unter Erstellen einer Anforderung.

Accept

Die meisten GitHub REST-API-Endpunkte geben an, dass Sie einen Accept-Header mit einem Wert von application/vnd.github+json übergeben sollten. Der Wert des Accept-Headers ist ein Medientyp. Weitere Informationen zu Medientypen findest du unter Medientypen.

X-GitHub-Api-Version

Sie sollten diesen Header verwenden, um eine Version der REST-API anzugeben, die für Ihre Anforderung verwendet werden soll. Weitere Informationen finden Sie unter API-Versionen.

User-Agent

Alle API-Anforderungen müssen einen gültigen User-Agent-Header enthalten. Der User-Agent-Header identifiziert den/die Benutzer*in oder die Anwendung, welche die Anforderung vornimmt.

Das folgende ist ein Beispiel User-Agent für eine App mit dem Namen Awesome-Octocat-App:

User-Agent: Awesome-Octocat-App

Anforderungen ohne User-Agent-Header werden abgelehnt. Wenn Sie einen ungültigen User-Agent-Header angeben, erhalten Sie eine 403 Forbidden-Antwort.

Medientypen

Sie können einen oder mehrere Medientypen angeben, indem Sie sie dem Accept-Header Ihrer Anforderung hinzufügen. Weitere Informationen zum Accept-Header findest du unter Accept.

Medientypen geben das Format der Daten an, die Sie von der API verbrauchen möchten. Medientypen sind ressourcenspezifisch, sodass sie unabhängig voneinander geändert werden können und Formate unterstützen, die von anderen Ressourcen nicht unterstützt werden. In der Dokumentation für die einzelnen GitHub REST-API-Endpunkte werden die von ihnen jeweils unterstützten Medientypen beschrieben. Weitere Informationen findest du unter Dokumentation zu GitHub-REST-API.

Die gängigsten Medientypen, die von der GitHub-REST-API unterstützt werden, sind application/vnd.github+json und application/json.

Es gibt benutzerdefinierte Medientypen, die mit einigen Endpunkten verwendet werden können. Zum Beispiel unterstützt die REST-API zum Verwalten von Commits und Pull Requests die Medientypen diff, patch und sha. Die Medientypen full, raw, text, oder html werden von einigen anderen Endpunkten verwendet.

Alle benutzerdefinierten Medientypen für GitHub sehen so aus: application/vnd.github.PARAM+json, wobei PARAM der Name des Medientyps ist. Um z. B. den Medientyp raw anzugeben, würden Sie beispielsweise application/vnd.github.raw+json verwenden.

Ein Beispiel für eine Anforderung, die Medientypen verwendet, findest du unter Erstellen einer Anforderung.

Authentifizierung

Viele Endpunkte erfordern die Authentifizierung oder senden im Fall einer Authentifizierung zusätzliche Informationen zurück. Darüber hinaus können Sie mehr Anforderungen pro Stunde stellen, wenn Sie authentifiziert sind.

Parameter

Viele API-Methoden erfordern oder ermöglichen es Ihnen, zusätzliche Informationen in Parametern in Ihren Anforderung zu senden. Es gibt verschiedene Typen von Parametern: Pfadparameter, Textparameter und Abfrageparameter.

Pfadparameter

Pfadparameter ändern den Endpunktspfad. Diese Parameter sind für Ihre Anforderung erforderlich. Weitere Informationen finden Sie unter Path.

Körperparameter

Textparameter ermöglichen es dir, zusätzliche Daten an die API zu übergeben. Diese Parameter können je nach Endpunkt optional oder erforderlich sein. Ein Textparameter kann es Ihnen z. B. ermöglichen, beim Erstellen eines neuen Issues einen Issue-Titel anzugeben oder bestimmte Einstellungen beim Aktivieren oder Deaktivieren eines Features anzugeben. In der Dokumentation zu jedem GitHub REST-API-Endpunkt werden die unterstützten Parameter des Anfragekörpers beschrieben. Weitere Informationen findest du unter Dokumentation zu GitHub-REST-API.

Beim „Erstellen eines Issues“-Endpunkt müssen Sie zum Beispiel in Ihrer Anforderung einen Titel für das neue Issue angeben. Darüber hinaus können Sie optional andere Informationen angeben, z. B. Text, der in den Issue-Text eingefügt werden soll, Benutzer*innen, die dem neuen Issue zugewiesen werden sollen, oder Bezeichnungen, die auf den neuen Issue angewendet werden sollen. Ein Beispiel für eine Anforderung, die Textparameter verwendet, findest du unter Erstellen einer Anforderung.

Sie müssen Ihre Anforderung authentifizieren, um Textparameter weiterzugeben. Weitere Informationen findest du unter Authentifizierung.

Abfrageparameter

Mithilfe von Abfrageparametern kannst du steuern, welche Daten für eine Anforderung zurückgegeben werden. Diese Parameter sind üblicherweise optional. In der Dokumentation für die einzelnen GitHub REST-API-Endpunkte werden die von ihr unterstützten Abfrageparameter beschrieben. Weitere Informationen findest du unter Dokumentation zu GitHub-REST-API.

Beispielsweise gibt der Endpunkt „Öffentliche Ereignisse auflisten“ standardmäßig dreißig Issues zurück. Sie können mit dem Abfrageparameter per_page angeben, dass anstelle von 30 Issues zwei Issues zurückgegeben werden. Sie können den Abfrageparameter page verwenden, um nur die erste Seite der Ergebnisse abzurufen. Ein Beispiel für eine Anforderung, die Abfrageparameter verwendet, findest du unter Erstellen einer Anforderung.

Erstellen einer Anforderung

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

Verwendung der Antwort

Nachdem Sie eine Anforderung gestellt haben, sendet die API den Statuscode der Antwort, die Antwortheader und möglicherweise einen Antworttext zurück.

Informationen zu Antwortcodes und Headern

Jede Anforderung gibt einen HTTP-Statuscode zurück, der den Erfolgsstatus der Antwort anzeigt. Weitere Informationen zu Antwortcodes findest du in der MDN-Dokumentation zu HTTP-Antwortstatuscodes.

Außerdem enthält die Antwort Header, die weitere Informationen zur Antwort liefern. Header, die mit X- oder x- beginnen, gelten speziell für GitHub. Die Header x-ratelimit-remaining und x-ratelimit-reset informieren dich zum Beispiel darüber, wie viele Anforderungen du in einem bestimmten Zeitraum ausführen kannst.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Informationen zum Antwortkörper

Bei vielen Endpunkten wird ein Antworttext zurückgesendet. Sofern nicht anders angegeben, verwendet der Antworttext das JSON-Format. Leere Felder werden als null aufgenommen, anstatt weggelassen zu werden. Alle Zeitstempel werden im UTC-Zeitformat nach ISO 8601 YYYY-MM-DDTHH:MM:SSZ zurückgesendet.

Im Gegensatz zur GraphQL-API, bei der du die gewünschten Informationen angibst, liefert die REST-API in der Regel mehr Informationen als du benötigst. Falls gewünscht, kannst du die Antwort analysieren, um bestimmte Informationen herauszufiltern.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Detaillierte Darstellungen im Vergleich zu Zusammenfassungsdarstellungen

Eine Antwort kann alle Attribute für eine Ressource oder nur eine Teilmenge von Attributen enthalten, je nachdem, ob Sie eine einzelne Ressource oder eine Liste von Ressourcen fetchen.

• Wenn Sie eine einzelne Ressource z. B. ein bestimmtes Repository, abrufen, enthält die Antwort in der Regel alle Attribute für diese Ressource. Dies ist die „detaillierte“ Darstellung der Ressource.
• Wenn Sie eine Liste von Ressourcen fetchen, z. B. eine Liste mehrerer Repositorys, enthält die Antwort nur eine Teilmenge der Attribute für jede Ressource. Dies ist die „Zusammenfassungsdarstellung“ der Ressource.

Beachten Sie, dass die Autorisierung manchmal die Anzahl der Details in einer Darstellung beeinflusst.

Der Grund dafür ist, dass einige Attribute für die API rechenintensiv sind, so dass GitHub diese Attribute aus der Zusammenfassungsdarstellung ausschließen. Um diese Attribute zu erhalten, können Sie die detaillierte Darstellung abrufen.

Die Dokumentation enthält eine Beispielantwort für jede API-Methode. Die Beispielantwort zeigt alle Attribute an, die von dieser Methode zurückgegeben werden.

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"

Nächste Schritte

In diesem Artikel wurde gezeigt, wie du Issues in einem Repository auflisten und erstellen kannst. Um mehr Übung zu bekommen, kannst du versuchen, ein Issue zu kommentieren, den Titel eines Issue zu bearbeiten oder ein Issue zu schließen. Weitere Informationen finden Sie unter dem Endpunkt „Erstellen eines Kommentars zu einem Issue“ und Endpunkt „Aktualisieren eines Issues“.

Weitere Informationen zu anderen Endpunkten, die Sie verwenden können, finden Sie in der REST-Referenzdokumentation.