Skip to main content

Erste Schritte mit der REST-API

Erfahre, wie du die GitHub-REST-API verwendest.

Informationen zur GitHub-REST-API

Dieser Artikel beschreibt, wie du die GitHub-REST-API mit der GitHub CLI, mit JavaScript oder cURL nutzen kannst. Einen Leitfaden für den schnellen Einstieg findest du unter Schnellstart für die GitHub-REST-API.

Wenn du eine Anforderung an die REST-API sendest, gibst du eine HTTP-Methode und einen Pfad an. Darüber hinaus kannst du auch Anforderungsheader sowie Pfad-, Abfrage- oder Textparameter angeben. Die API gibt den Antwortstatuscode, Antwortheader und potenziell einen Antworttext zurück.

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

Weitere Informationen zu den APIs von GitHub findest du unter Informationen zu GitHub-APIs.

Ausführen einer Anforderung

Um eine Anforderung auszuführen, musst du zuerst die HTTP-Methode und den Pfad für den gewünschten Vorgang ermitteln. Der Vorgang „Get Octocat“ verwendet beispielsweise die Methode GET und den Pfad /octocat. Die vollständige Referenzdokumentation für diesen Vorgang findest du unter Get Octocat.

Hinweis: Du musst die GitHub CLI installieren, um die Befehle in den GitHub CLI-Beispielen verwenden zu können. Anweisungen zur Installation findest du im GitHub CLI-Repository.

Wenn du noch nicht bei der GitHub CLI authentifiziert bist, musst du dich mit dem Unterbefehl gh auth login authentifizieren, bevor du eine Anforderung ausführen kannst. Weitere Informationen findest du unter Authentifizierung.

Um eine Anforderung mit der GitHub CLI auszuführen, verwende den Unterbefehl api zusammen mit dem Pfad. Verwende das Flag --method oder -X, um die Methode anzugeben.

gh api /octocat --method GET

Hinweis: Du musst octokit installieren und importieren, um die in den JavaScript-Beispielen verwendete Bibliothek „Octokit.js“ nutzen zu können. Weitere Informationen findest du in der Octokit.js-Infodatei.

Um eine Anforderung mithilfe von JavaScript auszuführen, kannst du „Octokit.js“ verwenden. Weitere Informationen findest du unter Skripterstellung mit der REST-API und JavaScript.

Erstelle zunächst eine Instanz von Octokit. Lege die Basis-URL auf http(s)://HOSTNAME/api/v3 fest. Ersetze [hostname] durch den Namen von your GitHub Enterprise Server instance.

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
});

Verwende dann die request-Methode, um Anforderungen auszuführen. Übergib die HTTP-Methode und den Pfad als erstes Argument.

await octokit.request("GET /octocat", {});

Füge die Basis-URL für die GitHub-REST-API, http(s)://HOSTNAME/api/v3, am Anfang des Pfads ein, um die vollständige URL zu erhalten: http(s)://HOSTNAME/api/v3/octocat. Ersetze [hostname] durch den Namen von your GitHub Enterprise Server instance.

Verwende den Befehl curl in deiner Befehlszeile. Verwende das Flag --request oder -X, gefolgt von der HTTP-Methode. Verwende das Flag --url, gefolgt von der vollständigen URL.

curl --request GET \
--url "https://api.github.com/octocat"

Hinweis: Wenn du eine Meldung der Art „command not found: curl“ erhältst, musst du cURL möglicherweise herunterladen und installieren. Weitere Informationen findest du auf der Downloadseite für das cURL-Projekt.

Lies weiter, um zu erfahren, wie du dich authentifizieren, Parameter senden und die Antwort verwenden kannst.

Authentifizierung

Viele Vorgänge erfordern eine Authentifizierung oder geben zusätzliche Informationen zurück, wenn du authentifiziert bist. Außerdem kannst du eine größere Anzahl von Anforderungen pro Stunde ausführen, wenn du authentifiziert bist.

Obwohl einige REST-API-Vorgänge ohne Authentifizierung zugänglich sind, musst du dich bei der GitHub CLI authentifizieren, um den Unterbefehl api verwenden zu können.

Informationen zu Token

Du kannst deine Anforderung authentifizieren, indem du ein Token hinzufügst.

Wenn du die GitHub-REST-API für den privaten Gebrauch nutzen möchtest, kannst du ein personal access token erstellen. Für die in diesem Artikel verwendeten REST-API-Vorgänge wird der Bereich repo für persönliche Zugangstoken personal access tokens. Für andere Vorgänge sind möglicherweise andere Bereiche erforderlich. Weitere Informationen zum Erstellen eines personal access token findest du unter Erstellen eines personal access token.

Wenn du die API im Namen einer Organisation oder eines anderen Benutzers nutzen möchtest, empfiehlt GitHub, dass du eine GitHub App verwendest. Wenn ein Vorgang für GitHub Apps verfügbar ist, findest du in der REST-Referenzdokumentation für diesen Vorgang den Hinweis „Funktioniert mit GitHub Apps“. Für die in diesem Artikel verwendeten REST-API-Vorgänge werden issues-Lese- und -Schreibberechtigungen für GitHub Apps benötigt. Für andere Vorgänge sind möglicherweise andere Berechtigungen erforderlich. Weitere Informationen findest du unter Erstellen einer GitHub App, Authentifizierung bei GitHub Apps und Identifizieren und Autorisieren von Benutzern für GitHub Apps.

Wenn du die API in einem GitHub Actions-Workflow verwenden möchtest, empfiehlt GitHub, dass du dich mit dem integrierten GITHUB_TOKEN authentifizierst, anstatt ein Token zu erstellen. Du kannst den GITHUB_TOKEN mit dem Schlüssel permissions Berechtigungen erteilen. Weitere Informationen findest du unter Automatische Tokenauthentifizierung.

Beispiel für die Authentifizierung

Bei der GitHub CLI ist es nicht nötig, im Voraus ein Zugriffstoken zu erstellen. Verwende den Unterbefehl auth login, um dich bei der GitHub CLI zu authentifizieren:

gh auth login

Mit dem Flag --scopes kannst du angeben, welche Bereiche du festlegen möchtest. Wenn du dich mit einem von dir erstellten Token authentifizieren möchtest, kannst du das Flag --with-token verwenden. Weitere Informationen findest du in der Dokumentation zu GitHub CLI auth login.

Warnung: Behandle dein Zugriffstoken wie ein Kennwort.

Um dein Token zu schützen, kannst du es als Geheimnis speichern und dein Skript über GitHub Actions ausführen. Weitere Informationen findest du unter Verschlüsselte Geheimnisse.

Wenn diese Optionen nicht verfügbar sind, solltest du einen anderen Dienst wie zum Beispiel die 1Password CLI nutzen, um dein Token sicher zu speichern.

Um dich bei der Octokit.js-Bibliothek zu authentifizieren, kannst du dein Token übergeben, wenn du eine Instanz von Octokit erstellst. Ersetze YOUR-TOKEN durch dein Token. Replace [hostname] durch den Namen von your GitHub Enterprise Server instance.

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: 'YOUR-TOKEN',
});

Warnung: Behandle dein Zugriffstoken wie ein Kennwort.

Um die Sicherheit deines Kontos zu gewährleisten, kannst du die GitHub CLI anstelle von cURL verwenden. Die GitHub CLI übernimmt die Authentifizierung für dich. Weitere Informationen findest du in der GitHub CLI-Version dieser Seite.

Wenn diese Optionen nicht verfügbar sind, solltest du einen anderen Dienst wie zum Beispiel die 1Password CLI nutzen, um dein Token sicher zu speichern.

Bei cURL sendest du einen Authorization-Header mit deinem Token. Ersetze YOUR-TOKEN durch dein Token:

curl --request GET \
--url "https://api.github.com/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.

Authentifizierungsbeispiel für GitHub Actions

Du kannst auch das Schlüsselwort run verwenden, um GitHub CLI-Befehle in deinen GitHub Actions-Workflows auszuführen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Anstatt den Befehl gh auth login zu verwenden, übergibst du dein Token als Umgebungsvariable namens GH_TOKEN. GitHub empfiehlt, dass du dich mit dem integrierten GITHUB_TOKEN authentifizierst, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verschlüsselte Geheimnisse.

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh api /octocat

Du kannst auch das Schlüsselwort run verwenden, um deine JavaScript-Skripts in deinen GitHub Actions-Workflows auszuführen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

GitHub empfiehlt, dass du dich mit dem integrierten GITHUB_TOKEN authentifizierst, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verschlüsselte Geheimnisse.

Der nachstehende Beispielworkflow übernimmt folgende Aufgaben:

  1. Überprüfen des Repositoryinhalts
  2. Einrichten von Node.js
  3. Installieren von octokit
  4. Speichern des Werts von GITHUB_TOKEN als Umgebungsvariable namens TOKEN und Ausführen des Skripts .github/actions-scripts/use-the-api.mjs, das auf diese Umgebungsvariable als process.env.TOKEN zugreifen kann

Beispielworkflow:

on:
  workflow_dispatch:
jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Check out repo content
        uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: '16.17.0'
          cache: npm

      - name: Install dependencies
        run: npm install octokit

      - name: Run script
        env:
          TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          node .github/actions-scripts/use-the-api.mjs

JavaScript-Beispielskript mit dem Dateipfad .github/actions-scripts/use-the-api.mjs:

import { Octokit } from "octokit";

const octokit = new Octokit({ 
  baseUrl: "http(s)://HOSTNAME/api/v3",
  auth: process.env.TOKEN,
});

await octokit.request("GET /octocat", {});

Anstatt dein Skript in einer separaten Datei zu speichern und das Skript von deinem Workflow aus auszuführen, kannst du die actions/github-script-Aktion verwenden, um ein Skript auszuführen. Weitere Informationen findest du in der actions/github-Infodatei.

jobs:
  use_api_via_script:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - uses: actions/github-script@v6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            await github.request('GET /octocat', {})

Du kannst auch das Schlüsselwort run verwenden, um cURL-Befehle in deinen GitHub Actions-Workflows auszuführen. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

GitHub empfiehlt, dass du dich mit dem integrierten GITHUB_TOKEN authentifizierst, anstatt ein Token zu erstellen. Wenn das nicht möglich ist, speichere dein Token als Geheimnis, und ersetze GITHUB_TOKEN im folgenden Beispiel durch den Namen deines Geheimnisses. Weitere Informationen zu GITHUB_TOKEN findest du unter Automatische Tokenauthentifizierung. Weitere Informationen zu Geheimnissen findest du unter Verschlüsselte Geheimnisse.

jobs:
  use_api:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          curl --request GET \
          --url "https://api.github.com/octocat" \
          --header "Authorization: Bearer $GH_TOKEN"

Verwenden von Headern

Die meisten Vorgänge schreiben vor, dass du einen Accept-Header mit dem Wert application/vnd.github+json übergeben musst. Bei anderen Vorgängen musst du möglicherweise einen anderen Accept-Header oder zusätzliche Header senden.

Um einen Header mit der GitHub CLI zu senden, verwende das Flag --header oder -H, gefolgt von dem Header im Format key: value.

gh api --header 'Accept: application/vnd.github+json' --method GET /octocat

Die Octokit.js-Bibliothek übergibt automatisch den Accept: application/vnd.github+json-Header. Um zusätzliche Header oder einen anderen Accept-Header zu übergeben, füge dem Objekt eine headers-Eigenschaft hinzu, die als zweites Argument an die request-Methode übergeben wird. Der Wert der Eigenschaft headers ist ein Objekt mit den Headernamen als Schlüssel und den Headerwerten als Werte. Es folgt ein Beispiel zum Senden eines content-type-Headers mit dem Wert text/plain:

await octokit.request("GET /octocat", {
  headers: {
    "content-type": "text/plain",
  },
});

Um einen Header mit cURL zu senden, verwende das Flag --header oder -H, gefolgt von dem Header im Format key: value.

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN"

Verwenden von Pfadparametern

Pfadparameter ändern den Vorgangspfad. Der Pfad zum Auflisten von Issues für ein Repository lautet beispielsweise /repos/{owner}/{repo}/issues. Die geschweiften Klammern {} bezeichnen Pfadparameter, die du angeben musst. In diesem Fall musst du den Besitzer und den Namen des Repositorys angeben. Die Referenzdokumentation für diesen Vorgang findest du unter Auflisten von Issues für ein Repository.

Hinweis: Damit dieser Befehl für your GitHub Enterprise Server instance funktioniert, musst du octocat/Spoon-Knife durch ein Repository im Besitz von your GitHub Enterprise Server instance ersetzen. Andernfalls musst du den Befehl gh auth login erneut ausführen, um dich bei GitHub.com statt your GitHub Enterprise Server instance zu authentifizieren.

Um Issues aus dem octocat/Spoon-Knife Repository abzurufen, ersetze {owner} durch octocat und {repo} durch Spoon-Knife.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues

Hinweis: Damit dieses Beispiel für your GitHub Enterprise Server instance funktioniert, musst du octocat/Spoon-Knife durch ein Repository im Besitz von your GitHub Enterprise Server instance ersetzen. Andernfalls erstellst du eine neue Octokit-Instanz und gibst baseURL nicht an.

Wenn du eine Anforderung mit Octokit.js stellst, werden alle Parameter (einschließlich der Pfadparameter) in einem Objekt als zweites Argument an die Methode request übergeben. Um Issues aus dem octocat/Spoon-Knife Repository abzurufen, gib owner als octocat und repo als Spoon-Knife an.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife"
});

Um Issues aus dem octocat/Spoon-Knife Repository abzurufen, ersetze {owner} durch octocat und {repo} durch Spoon-Knife. Um den vollständigen Pfad zu erhalten, füge die Basis-URL für die GitHub-REST-API am Pfadanfang ein, https://api.github.com: https://api.github.com/repos/octocat/Spoon-Knife/issues.

Hinweis: Wenn du your GitHub Enterprise Server instance anstelle von GitHub.com verwenden möchtest, musst du http(s)://HOSTNAME/api/v3 anstelle von https://api.github.com verwenden und [hostname] durch den Namen von your GitHub Enterprise Server instance ersetzen. Ersetze octocat/Spoon-Knife durch ein Repository im Besitz von your GitHub Enterprise Server instance.

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

Der Vorgang liefert eine Liste der Issues sowie Daten zu jedem Issue. Weitere Informationen zur Verwendung der Antwort findest du im Abschnitt Verwenden der Antwort.

Verwenden von Abfrageparametern

Mithilfe von Abfrageparametern kannst du steuern, welche Daten für eine Anforderung zurückgegeben werden. Mit einem Abfrageparameter kannst du zum Beispiel angeben, wie viele Elemente zurückgegeben werden, wenn die Antwort paginiert wird.

Standardmäßig gibt der Vorgang zum Auflisten von Issues für das Repository dreißig Issues zurück, die in absteigender Reihenfolge nach dem Erstellungsdatum sortiert sind. Du kannst mit dem Parameter per_page angeben, dass anstelle von 30 Issues zwei Issues zurückgegeben werden. Mit dem Parameter sort kannst du die Issues nach dem Datum der letzten Aktualisierung sortieren, anstatt nach dem Erstellungsdatum. Du kannst den Parameter direction verwenden, um die Ergebnisse in aufsteigender statt in absteigender Reihenfolge zu sortieren.

Verwende für die GitHub CLI das Flag -F, um einen Parameter zu übergeben, bei dem es sich um eine Zahl, einen booleschen Wert oder NULL handelt. Verwende -f, um Zeichenfolgenparameter zu übergeben.

Hinweis: Die GitHub CLI akzeptiert derzeit keine Parameter, bei denen es sich um Arrays handelt. Weitere Informationen findest du in diesem Issue.

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2 -f sort=updated -f direction=asc

Wenn du eine Anforderung mit Octokit.js stellst, werden alle Parameter (einschließlich der Abfrageparameter) in einem Objekt als zweites Argument an die Methode request übergeben.

await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
  sort: "updated",
  direction: "asc",
});

Für cURL fügst du ein ? am Pfadende ein und hängst dann den Namen und den Wert deines Abfrageparameters in der Form parameter_name=value an. Trenne mehrere Abfrageparameter durch &.

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

Der Vorgang liefert eine Liste der Issues sowie Daten zu jedem Issue. Weitere Informationen zur Verwendung der Antwort findest du im Abschnitt Verwenden der Antwort.

Verwenden von Textparametern

Textparameter ermöglichen es dir, zusätzliche Daten an die API zu übergeben. Beim Vorgang zum Erstellen eines Issues musst du zum Beispiel einen Titel für das neue Issue angeben. Hier kannst du außerdem weitere Informationen angeben, z. B. den Text, der in den Textteil des Issues aufgenommen werden soll. Die vollständige Referenzdokumentation für diesen Vorgang findest du unter Erstellen eines Issues.

Der Vorgang zum Erstellen eines Issues verwendet denselben Pfad wie der in den obigen Beispielen gezeigte Vorgang zum Auflisten von Issues im Repository, aber er verwendet anstelle der GET-Methode eine POST-Methode.

Verwende für die GitHub CLI das Flag -F, um einen Parameter zu übergeben, bei dem es sich um eine Zahl, einen booleschen Wert oder NULL handelt. Verwende -f, um Zeichenfolgenparameter zu übergeben.

Hinweis: Die GitHub CLI akzeptiert derzeit keine Parameter, bei denen es sich um Arrays handelt. Weitere Informationen findest du in diesem Issue.

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

Wenn du eine Anforderung mit „Octokit.js“ stellst, werden alle Parameter (einschließlich der Textparameter) in einem Objekt als zweites Argument an die Methode request übergeben.

await octokit.request("POST /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  title: "Created with the REST API",
  body: "This is a test issue created by the REST API",
});

Bei cURL verwendest du das Flag --data, um die Textparameter in einem JSON-Objekt zu übergeben.

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

Der Vorgang erstellt ein Issue und gibt Daten zu dem neuen Issue zurück. Suche in der Antwort nach der html_url deines Issues, und navigiere im Browser zu deinem Issue. Weitere Informationen zur Verwendung der Antwort findest du im Abschnitt Verwenden der Antwort.

Verwenden der Antwort

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.

Um den Statuscode und die Header anzuzeigen, verwende beim Senden deiner Anforderung das Flag --include oder --i.

Betrachte beispielsweise die folgende Anforderung:

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

Sie gibt den Antwortcode und Header wie folgt zurück:

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, 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: ; rel="next", ; 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, X-GitHub-OTP, 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

In diesem Beispiel lautet der Antwortcode 200, d. h. die Anforderung war erfolgreich.

Wenn du eine Anforderung mit „Octokit.js“ ausführst, gibt die Methode request eine Zusage zurück. Wenn die Anforderung erfolgreich war, wird die Zusage in ein Objekt aufgelöst, das den HTTP-Statuscode der Antwort (status) und die Antwortheader (headers) enthält. Wenn ein Fehler auftritt, wird die Zusage in ein Objekt aufgelöst, das den HTTP-Statuscode der Antwort (status) und die Antwortheader (response.headers) enthält.

Du kannst einen try/catch-Block verwenden, um einen eventuell auftretenden Fehler abzufangen. Wenn die Anforderung im folgenden Skript beispielsweise erfolgreich ist, protokolliert das Skript den Statuscode und den Wert des x-ratelimit-remaining-Headers. War die Anforderung nicht erfolgreich, protokolliert das Skript den Statuscode, den Wert des x-ratelimit-remaining-Headers und die Fehlermeldung.

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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}`)
}

Um den Statuscode und die Header anzuzeigen, verwende beim Senden deiner Anforderung das Flag --include oder --i.

Betrachte beispielsweise die folgende Anforderung:

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

Sie gibt den Antwortcode und Header wie folgt zurück:

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: ; rel="next", ; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, 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

In diesem Beispiel lautet der Antwortcode 200, d. h. die Anforderung war erfolgreich.

Informationen zum Antworttext

Bei vielen Vorgängen wird ein Antworttext zurückgegeben. Sofern nicht anders angegeben, verwendet der Antworttext das JSON-Format. Diese Anforderung liefert zum Beispiel eine Liste von Issues mit Daten zu jedem Issue:

gh api --header 'Accept: application/vnd.github+json' --method GET /repos/octocat/Spoon-Knife/issues -F per_page=2
await octokit.request("GET /repos/{owner}/{repo}/issues", {
  owner: "octocat",
  repo: "Spoon-Knife",
  per_page: 2,
});
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"

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.

Du kannst zum Beispiel > verwenden, um die Antwort in eine Datei umzuleiten:

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

Dann kannst mit jq den Titel und die Autoren-ID für jedes Issue abrufen:

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

Die beiden vorherigen Befehle liefern eine Ausgabe ähnlich der folgenden:

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

Weitere Informationen zu jq findest du in der jq-Dokumentation und unter jq play.

Du kannst zum Beispiel den Titel und die Autoren-ID für jedes Issue abrufen:

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "octocat",
    repo: "Spoon-Knife",
    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}`)
}

Du kannst zum Beispiel > verwenden, um die Antwort in eine Datei umzuleiten:

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

Dann kannst mit jq den Titel und die Autoren-ID für jedes Issue abrufen:

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

Die beiden vorherigen Befehle liefern eine Ausgabe ähnlich der folgenden:

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

Weitere Informationen zu jq findest du in der jq-Dokumentation und unter jq play.

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 zu diesen Vorgängen findest du unter Erstellen eines Kommentars zu einem Issue und Aktualisieren eines Issues.

Weitere Informationen zu den Vorgängen, die du verwenden kannst, findest du in der REST-Referenzdokumentation.