Informationgrid - InGrid Editor Schnittstelle

Allgemeines

Dieser Abschnitt beschreibt optionale API Endpunkte von dem InGrid Editor und die Authentifizierung der Schnittstelle.

Unterstützte Schnittstellen:

CSW-t nach ISO 19139 (2007)
OGC Records API

Konfiguration

Mit dem Profil csw-t kann der IGE-NG um eine schreibende CSW-t Schnittstelle (POST Methode) für INSERT, UPDATE & DELETE erweitert werden.

Mit dem Profil ogc-api kann der IGE-NG um eine schreibende OGC konforme Schnittstelle erweitert werden.

Endpunkte im Überblick

Eine ausführliche Dokumentation der Endpunkte ist über das Swagger-UI zu erreichen. Es dient als Hilfestellung für Testanfragen und gibt detailierte Auskunft über Anfrage-Parameter und Pfad-Struktur.

https://ige-ng.informationgrid.eu/swagger-ui/index.html

Um einen API-Endpunkt über die Swagger-Benutzeroberfläche zu testen, müssen Sie den zuständigen Server auswählen (Dropdown-Menü “Server”) und ein gültiges Bearer-Token eingeben (Schaltfläche “Authorise”).

CSW-t Transaction

Method	Type	Description
POST	CSW-t	INSERT, UPDATE & DELETE transaction Endpoint: `/api/cswt` Example: `../api/cswt?SERVICE=CSW&REQUEST=Transaction&catalog=CATALOG_ID`

OGC Records APIs

Method	Type	Description
GET	Landing Page	Get general information about OGC API Records Endpoint: `/api/ogc`
GET	Conformance	Get conformance class of OGC API Records Endpoint: `/api/ogc/conformance`
GET	Collections	Get multiple collections Endpoint: `/api/ogc/collections`
GET	Collection	Get collection by collection-ID Endpoint: `/api/ogc/collections/{collectionId}`
GET	Records	Get multiple records of a collection Endpoint: `/api/ogc/collections/{collectionId}/items`
GET	Record	Get record by record-ID Endpoint: `/api/ogc/collections/{collectionId}/items/{recordId}`
POST	Records	Insert multiple records into a collection Endpoint: `/api/ogc/collections/{collectionId}/items`
PUT	Record	Replace/update an existing resource in a collection with a replacement resource with the same resource identifier. Endpoint: `/api/ogc/collections/{collectionId}/items/{recordId}`
DELETE	Record	Delete a record by record-ID Endpoint: `/api/ogc/collections/{collectionId}/items/{recordId}`

NOTE: Collection verweist auf einen Katalog. Record verweist auf ein Dokument (dataset, address).

Authentifizierung

Alle APIs sind mit OAuth 2.0 über Keycloak gesichert. Um mit Endpunkten zu interagieren, muss zunächst ein Bearer-Token erstellt werden und in der Anfrage mit übergeben werden.

Überblick über die erforderlichen Variablen und Berechtigungsnachweise:

Variable	Description
$KEYCLOAK_HOST	Keycloak Host e.g. `https://keycloak.informationgrid.eu`
$REALM	Legen Sie den Keycloak-Realm fest, der eine Reihe von Benutzern, Anmeldeinformationen, Rollen und Gruppen verwaltet (e.g. “InGrid”).
$CLIENTID	Keycloak client ID (e.g. “ige-ng-frontend”)
$CLIENTSECRET	Keycloak client secret (e.g. “admin”)
$USERNAME	Benutzername (InGird Editor Login)
$PASSWORD	Passwort (InGrid Editor Login)
Grant type	Type: Password Credential
Access Token URL	`KEYCLOAK_HOST`/realms/`$REALM`/protocol/openid-connect/token
Refresh Token URL	`KEYCLOAK_HOST`/realms/`$REALM`/protocol/openid-connect/token

NOTE: Zugangstokens sind 1 Minute lang gültig. Nach Ablauf der Gültigkeitsdauer muss das Token mit einem Refresh-Token aufgefrischt werden.

Token anfragen

In diesem Abschnitt wird beschrieben, wie Sie Zugangstoken und Refresh-Token via cURL erhalten können.

Ersetzen Sie folgende Variable und führen Sie cURL aus: $KEYCLOAK_HOST, $REALM, $USERNAME, $PASSWORD, $CLIENTID, $CLIENTSECRET

curl -X POST
    $KEYCLOAK_HOST/realms/$REALM/protocol/openid-connect/token
    -H 'Content-Type: application/x-www-form-urlencoded'
    -d username=$USERNAME
    -d password=$PASSWORD
    -d grant_type=password
    -d client_id=$CLIENTID
    -d client_secret=$CLIENTSECRET

Die Antwort ist ein JSON-Objekt, das unter anderem Access-Token und Refresh-Token enthält. Beispiel einer Antwort:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInZGMZvcm1hdGlvbmdyaWQuZXUvcmVhbG1zL3JpZCIs...",
    "expires_in": 60,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I...",
    "token_type": "Bearer",
    "not-before-policy": 1632732926,
    "session_state": "1afef5ee-272c-4c4a-a181-3da38b432bac",
    "scope": "email profile"
}

Betrieb

Sobald Sie einen gültigen access_token erhalten haben (siehe “Authentifizierung”), können Sie die Schnittstellen aufrufen. Dazu müssen Sie den access_token als Bearer-Token in den Header beifügen.

OGC Records API Request

Beispiel für eine cURL-Anfrage für die OGC-Landing Page:

curl --location 'https://ige-ng.informationgrid.eu/api/ogc'
     --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInZGMZvcm1hdGlvbmdyaWQuZXUvcmVhbG1zL3JpZCIs...'

Beispiel für eine OGC API Antwort:

{
    "title": "OGC API Records",
    "description": "Access to InGrid via OGC API for Records."
}

CSW-t POST Request

Mit der CSW-t Schnittstelle können mehrere Dokument-Anfragen transaktional verarbeitet werden. Darunter zählen Insert, Update und Delete Anfragen. Im Folgenden sehen Sie ein Beispiel für eine cURL POST Request:

curl --location 'https://ige-ng.informationgrid.eu/api/cswt?SERVICE=CSW&REQUEST=Transaction&catalog=my-ingrid' 
--header 'Content-Type: application/xml' 
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInZGMZvcm1hdGlvbmdyaWQuZXUvcmVhbG1zL3JpZCIs...' 
--data-raw '<?xml version="1.0" encoding="UTF-8"?>
<csw:Transaction service="CSW" version="2.0.2"
    xmlns:csw="http://www.opengis.net/cat/csw/2.0.2"
    xmlns:ogc="http://www.opengis.net/ogc"
    xmlns:gmd="http://www.isotc211.org/2005/gmd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/cat/csw/2.0.2 http://schemas.opengis.net/csw/2.0.2/CSW-publication.xsd">

    <csw:Insert>
        <!-- ein vollständiges Dokument im Format ISO 19139 (2007)-->
    </csw:Insert>
    
    <csw:Update>
        <!-- ein vollständiges Dokument im Format ISO 19139 (2007) -->
        <csw:Constraint version="2.0.0">
            <ogc:Filter>
                <ogc:PropertyIsEqualTo>
                    <ogc:PropertyName>apiso:identifier</ogc:PropertyName>
                    <ogc:Literal>18c19e21-6931-4c8c-931e-79beefbfa7b2</ogc:Literal>
                </ogc:PropertyIsEqualTo>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Update>
    
    <csw:Delete>
        <csw:Constraint version="2.0.0">
            <ogc:Filter>
                <ogc:PropertyIsEqualTo>
                    <ogc:PropertyName>apsio:identifier</ogc:PropertyName>
                    <ogc:Literal>E6D08246-2B08-4551-8B99-8F75CCBBAD45</ogc:Literal>
                </ogc:PropertyIsEqualTo>
            </ogc:Filter>
        </csw:Constraint>
    </csw:Delete>

</csw:Transaction>'

In dem Tag <csw:Transaction> können mehrere Dokument-Anfragen gesammelt werden.

Klammern Sie ein Dokument mit <csw:Insert>, um es als neues Dokument hinzuzufügen.
Klammern Sie ein Dokument mit <csw:Update>, um ein bestehendes Dokument zu aktualisieren.
Klammern Sie eine Dokument-Id mit <csw:Delete> (siehe nachfolgendes Beispiel), um ein bestehendes Dokument zu löschen.

Mehr Informationen bzgl. ISO 19139 (2007) konformen Transaktionen und deren Struktur finden Sie unter dem Kapitel “CSW Schnittstelle”.