SHAPTH

Quick Start

Kompakter Einstieg in die Anbindung an die SHAPTH-API.

Technischer EinstiegDieser Quickstart führt durch den ersten API-Aufruf gegen die PRE-Umgebung. Das umfasst Informationen zum Vorbereiten der Zugangsdaten, zum Abrufen eines Access Tokens und zum anschließenden Ausführen einer kleinen GraphQL-Listenabfrage mit Variablen.Detaillierungen zu HTTP-Statuscodes, API-Fehlermeldungen, REST/XWasser-Nachrichtenflüssen und insbesondere zu rollenspezifischen Use Cases sind im allgemeinen Teil sowie in den rollenspezifischen Fachseiten beschrieben.
UmgebungPRE
AuthentifikationOAuth2 Client Credentials
Erster API-TestGraphQL-Listenabfrage
REST oder GraphQL für den ersten Test?Für diesen Quickstart wird GraphQL verwendet. Damit lässt sich schnell prüfen, ob Authentifikation, Endpoint und Berechtigungen grundsätzlich funktionieren. REST/XWasser ist dagegen für den Transport von XML-Nachrichten relevant, zum Beispiel für Prüfberichte, Untersuchungspläne, Jahresberichte, Quittungen, Rückweisungen und Nachrichtenabrufe. Diese Abläufe werden in den rollenbezogenen Use Cases detailliert beschrieben.
Zugangsdaten vorbereiten

Für die Authentifizierung werden Zugangsdaten für den technischen API-Client benötigt.

Zugangsdaten aus der PRE-Weboberfläche übernehmen Melden Sie sich mit den zugesendeten Testzugängen unter https://pre.www.shapth.de an.

  1. Passende Rolle auswählen.
  2. Je nach Rolle zu Zuständige Behörden, Zugelassene Untersuchungsstellen oder Betreiber wechseln.
  3. Beim eigenen Eintrag unter Aktion die Detailansicht öffnen.
  4. In der Detailansicht nach unten scrollen und die Angaben zur Anbindung von Drittsoftware übernehmen.
Access Token anfordern

Fordern Sie mit client_id und client_secret ein Access Token am PRE-Identity-Host an. Die Beispiele auf dieser Seite verwenden die PRE-Umgebung.

Access Token anfordern
curl -X POST "https://pre.id.shapth.de/realms/shapth/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "grant_type=client_credentials"
Token Response
{
"access_token": "<ACCESS_TOKEN>",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "Bearer",
"not-before-policy": 0,
"session_state": "<SESSION_STATE>",
"scope": "profile email"
}

Für die folgenden API-Aufrufe werden token_type und access_token zum Authorization-Header zusammengesetzt: Authorization: Bearer <ACCESS_TOKEN>.

Erste GraphQL-Abfrage ausführen

Die folgende Abfrage ruft eine kleine Liste zuständiger Behörden ab. Damit prüfen Sie, ob der GraphQL-Endpunkt erreichbar ist, der Bearer Token akzeptiert wird und der technische Client Registerdaten lesen darf.

GraphQL Query
query QuickStartOfficialList($input: OfficialListInput) {
officialList(input: $input) {
  total
  items {
    id
    name
    kind
    active
  }
}
}
Variablen
{
"input": {
  "pagination": {
    "page": 0,
    "limit": 1
  }
}
}
Request ausführen
curl -X POST "https://pre.api.shapth.de/api/graphql/service" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query QuickStartOfficialList($input: OfficialListInput) { officialList(input: $input) { total items { id name kind active } } }",
    "variables": {
      "input": {
        "pagination": {
          "page": 0,
          "limit": 1
        }
      }
    }
  }'
Alternativ im GraphQL Playground testen

Der Playground kann für manuelle GraphQL-Tests genutzt werden. Er unterstützt keine REST- oder XWasser-Aufrufe. Öffnen Sie die PRE-Umgebung und setzen Sie im Bereich Headers den Authorization-Header mit dem zuvor angeforderten Bearer Token.

PRE Playground öffnen
Header im Playground
{
"authorization": "Bearer <TOKEN>"
}
Beispiel-Response
{
"data": {
  "officialList": {
    "total": 421,
    "items": [
      {
        "id": "BY123GA801",
        "name": "Muster Gesundheitsamt",
        "kind": "GA",
        "active": true
      }
    ]
  }
}
}
Ergebnis einordnen

Wenn die Response ein data.officialList-Objekt enthält, ist die technische Anbindung für diesen ersten GraphQL-Leseaufruf grundsätzlich gelungen. total gibt die gegenwärtig insgesamt auflistbare Anzahl der Ergebnisse an. Dieser Wert ist vom aktuellen Datenbestand abhängig und kann sich verändern.

Wenn stattdessen eine Fehlermeldung erscheint, prüfen Sie zuerst Token, Endpoint und Berechtigung. Die detaillierte Einordnung von HTTP-Statuscodes und API-Fehlermeldungen steht im allgemeinen Teil der Dokumentation.

Fachlichen Einstieg auswählen

Nach dem erfolgreichen technischen Test wählen Sie den passenden Rollenpfad und integrieren den ersten Use Case oder kehren zurück zum allgemeinen Teil.

Softwarehersteller Fachanwendung BehördenSoftwarehersteller LIMS (Labore)Softwarehersteller Fachanwendung Wasserversorger (Betreiber)