REST-Jdbc — GitHub

Die GitHub REST API erfordert für die meisten Endpunkte Authentifizierung (Personal Access Token). Dieses Beispiel listet die Repositories des angemeldeten Benutzers.

Schnellstart mit dem JDBC-Client

SQL-Dateien lassen sich direkt mit dem Treiber-JAR ausführen:

java -jar restjdbc.jar github.sql

Die Datei github.sql enthält Verbindung und Beispiel-Abfragen. Vorgehen:

Treiber-JAR bereitstellen (absoluter Pfad zur restjdbc.jar)
In github.sql token=XXXX durch Ihr GitHub-Token ersetzen
Befehl im Ordner starten, in dem github.sql und github-spec.json liegen

Im JDBC-Client werden JDBC-URL und Connection Properties in einer Zeile verbunden — getrennt durch |, Properties durch Komma:

connect 'jdbc:rest:https://api.github.com|spec=github-spec.json,auth=bearer,token=ghp_…'

Nach Ausführung der Datei beendet quit den Client.

1. JDBC-URL

jdbc:rest:https://api.github.com

Die Basis-URL der API steht in der JDBC-URL.

Bestandteil	Wert
Treiber-Präfix	`jdbc:rest:`
API-Basis-URL	`https://api.github.com`
Schema (SQL)	`public` (Standard)

Beispiel-Verbindung (Java):

Properties props = new Properties();
props.setProperty("spec", "/pfad/zu/github-spec.json");
props.setProperty("auth", "bearer");
props.setProperty("token", System.getenv("GITHUB_TOKEN"));

Connection conn = DriverManager.getConnection(
    "jdbc:rest:https://api.github.com", props);

2. Connection Properties

Property	Wert für GitHub	Erforderlich
`spec`	Pfad zur Spec (siehe unten)	Ja
`auth`	`bearer`	Ja
`token`	Personal Access Token (PAT)	Ja
`password`	— (nicht für Bearer)	Nein
`user`	— (nicht für Bearer nötig)	Nein

Minimal:

props.setProperty("spec", "/pfad/zu/github-spec.json");
props.setProperty("auth", "bearer");
props.setProperty("token", "ghp_…");

Alternativ nur token setzen — der Treiber erkennt dann automatisch bearer.

Spec-Pfad: absoluter Pfad zu Ihrer lokalen Kopie der Spec-Datei.

Spec-Datei: github-spec.json

3. Spec-Datei

Datei: github-spec.json

Auszug:

{
  "entities": [
    {
      "name": "repos",
      "description": "Repositories of the authenticated user",
      "path": "/user/repos",
      "pagination": {
        "type": "page",
        "limitParam": "per_page",
        "pageParam": "page",
        "defaultLimit": 100
      },
      "write": false,
      "columns": [
        { "name": "id", "type": "BIGINT", "primaryKey": true },
        { "name": "name", "type": "VARCHAR" },
        { "name": "full_name", "type": "VARCHAR" },
        { "name": "private", "type": "BOOLEAN" },
        { "name": "description", "type": "VARCHAR" }
      ]
    }
  ]
}

Tabelle `repos`

SQL-Tabelle	REST-Pfad	Paginierung
`repos`	`/user/repos`	`page` mit `per_page` / `page` (Standard: 100 pro Seite)

GitHub liefert zusätzlich einen Link-Header (rel="next"). Der Treiber nutzt hier die expliziten Query-Parameter page und per_page, die GitHub ebenfalls unterstützt — der Treiber holt automatisch alle Seiten, bis eine leere Antwort kommt.

Beispiel-Ablauf bei vielen Repositories:

#	HTTP-Request	Ergebnis
1	`GET /user/repos?per_page=100&page=1`	erste 100 Repos
2	`GET /user/repos?per_page=100&page=2`	nächste 100 Repos
3	…	bis leere Liste

Für OData-APIs (z. B. Microsoft Graph) steht alternativ die Paginierung nextLink über @odata.nextLink in der JSON-Antwort zur Verfügung.

"write": false deaktiviert INSERT/UPDATE/DELETE für diese Entity (siehe Abschnitt 5).

4. Authentifizierung

GitHub verlangt einen Personal Access Token (classic oder fine-grained).

Token erstellen

GitHub → Settings → Developer settings → Personal access tokens
Token mit mindestens repo (private Repos) bzw. public_repo (nur öffentliche Repos) anlegen
Token sicher speichern — er wird nur einmal angezeigt

Bearer im Treiber

props.setProperty("auth", "bearer");
props.setProperty("token", "ghp_IhrToken");

Der Treiber sendet: Authorization: Bearer ghp_… sowie einen User-Agent-Header (von GitHub gefordert).

Token z. B. als Umgebungsvariable GITHUB_TOKEN setzen und in token übergeben.

5. SQL-Beispiele

SELECT

SELECT id, name, full_name, private FROM repos;

SELECT id, name, description FROM repos FILTER type=owner;

SELECT id, name FROM repos FILTER visibility=private;

SQL	HTTP
`SELECT … FROM repos`	`GET https://api.github.com/user/repos`
`SELECT … FROM repos FILTER type=owner`	`GET …/user/repos?type=owner`
`SELECT … FROM repos FILTER visibility=private`	`GET …/user/repos?visibility=private`

FILTER leitet Query-Parameter an GitHub weiter (serverseitig).

INSERT, UPDATE, DELETE

In github-spec.json ist "write": false gesetzt — Schreib-SQL schlägt fehl, bevor HTTP aufgerufen wird.

Warum: GitHub identifiziert Repositories für Änderungen über owner/repo (full_name), nicht über die numerische id. Das Standard-Mapping PUT/DELETE {path}/{id} passt daher nicht zur GitHub-API (PATCH /repos/{owner}/{repo}).

Konzeptionell würde ohne write: false gelten:

SQL	Default-HTTP (nicht GitHub-kompatibel)
`INSERT INTO repos (name, …) VALUES (…)`	`POST /user/repos` — kann funktionieren, erfordert Schreibrechte
`UPDATE repos SET … FILTER id=123`	`PUT /user/repos/123` — passt nicht zu GitHub
`DELETE FROM repos FILTER id=123`	`DELETE /user/repos/123` — passt nicht zu GitHub

Für echtes Schreiben bräuchte die Spec angepasste update/delete-Pfade mit {full_name} — das ist bewusst nicht Teil dieses Einstiegsbeispiels.

6. System-Tabellen

SELECT table_name, remarks FROM system.table_list;

SELECT column_name, type_name FROM system.column_list WHERE table_name = 'repos';

SELECT column_name FROM system.pk_list WHERE table_name = 'repos';

7. Hinweise

Rate Limits: GitHub begrenzt API-Aufrufe; bei 403 mit X-RateLimit-Remaining: 0 warten oder Token prüfen.
Fehler 401: Token fehlt, abgelaufen oder unzureichende Scopes.
Weitere Felder: owner, html_url, default_branch usw. sind verschachtelt — nur flache Spalten in der Spec sind abfragbar; verschachtelte JSON-Felder erfordern jsonPath in der Spec.