Zum Hauptinhalt springen

Metadata REST/API

Zur Integration bzw. zum Austausch von Metadaten mit anderen Applikationen werden REST-Schnittstellen angeboten, die den direkten lesenden und schreibenden Zugriff auf einzelne Metadatenobjekte ermöglichen.

Hinweis

In den nachfolgenden Beispielen werden zur Veranschaulichung die Datenbank test und der Server https://www.myserver.com verwendet (z.B. im Pfad https://www.myserver.com/rest/test/schemes). Diese Datenbank bzw. dieser Server ist in allen echten Aufrufen entsprechend zu ersetzen. Je nach Konfiguration muss die URL gegebenenfalls auch noch um den Context-Path erweitert werden (z.B. https://www.myserver.com/dataspot/rest/test/schemes).

Das dataspot REST/API ist eine Programmierschnittstelle die über HTTP einen direkten lesenden und schreibenden Zugriff auf einzelne Metadatenobjekte ermöglicht.

  • Die Strukturen und Properties richten sich nach dem dataspot Metamodell.
  • Die Metadaten können im Format JSON bereitgestellt werden.

Metamodell​

Das Metamodell dokumentiert alle Eigenschaften und Beziehungen der Metadatenobjekte und bildet die Grundlage für alle Zugriffe über das REST/API. Das Metamodell ist in der Datenbank meta unter folgender URL erreichbar:

https://www.myserver.com/web/meta
Hinweis

Die Datenbank meta kann in der Admin-Konsole (https://www.myserver.com/web/admin) erzeugt werden.

OpenAPI Spezifikation​

Die OpenAPI Spezifikation des REST/APIs (einschließlich aller Pfade, Parameter und Strukturen) ist unter folgender URL erreichbar:

https://www.myserver.com/specification/openapi.yaml
https://www.myserver.com/specification/openapi.json

Technische Grundlagen​

Das REST/API ist nach dem REST Paradigma für Softwarearchitektur erstellt.

Hinweis

Für den Aufruf des REST/APIs sind Zugangsdaten erforderlich. Je nach Authentifizierungsmethode (Benutzerkennung und Passwort, Single Sign-On, Same Sign-In, OpenID Connect) und eingesetzten Tools (z.B. curl) können unterschiedliche Mechanismen (z.B. Basic Authentication, Bearer Token) notwendig sein, um die Zugangsdaten bereitzustellen.

Der entsprechende Benutzer muss erfasst und - insbesondere bei schreibenden Zugriffen - ausreichend berechtigt sein.

Das REST/API folgt dem grundlegenden Entwurfsprinzip HATEOAS, welches es dem Aufrufer einer REST-Schnittstelle ermöglicht, nahezu ausschließlich über URLs zu navigieren, die vom Server bereitgestellt werden (und somit in der Antwort enthalten sind). Zur Implementierung von HATEOAS wird JSON Hypertext Application Language (HAL) verwendet (siehe auch Internet-Draft der IETF).

HTTP-Methoden​

Das REST/API unterstützt - je nach Endpunkt - eine oder mehrere der nachfolgenden HTTP-Methoden.

Hinweis

Falls die Applikation über einen Proxy-Server oder Reverse-Proxy erreicht wird, dürfen die verwendeten HTTP-Methoden (GET, POST, PUT, PATCH, DELETE) nicht blockiert werden.

POST​

Mit POST kann ein neues Metadatenobjekt angelegt werden:

  • Der technische oder fachliche Schlüssel des Metadatenobjekts ist in der URL kodiert.
  • Der Request-Payload enthält das neue Metadatenobjekt.
  • Der Response-Payload enthält das angelegte Metadatenobjekt.
# Neue Sammlung anlegen
POST /rest/test/schemes/Fachdatenmodell/collections

GET​

Mit GET kann ein vorhandenes Metadatenobjekt abgefragt werden:

  • Der technische oder fachliche Schlüssel des Metadatenobjekts ist in der URL kodiert.
  • Der Response-Payload enthält das abgefragte Metadatenobjekt.
# Sammlung 'Personal' abfragen
GET /rest/test/schemes/Fachdatenmodell/collections/Personal

Mit GET kann eine vorhandene Liste von Metadatenobjekten abgefragt werden:

  • Der technische oder fachliche Schlüssel der Liste von Metadatenobjekten ist in der URL kodiert.
  • Der Response-Payload enthält die abgefragte Liste von Metadatenobjekten.
# Liste von Enumerationen abfragen
GET /rest/test/schemes/Referenzdaten/enumerations

# Liste von Verantwortungen abfragen
GET /rest/test/schemes/Fachdatenmodell/attributedTo

PUT​

Mit PUT kann ein vorhandenes Metadatenobjekt geändert werden:

  • Der technische oder fachliche Schlüssel des Metadatenobjekts ist in der URL kodiert.
  • Der Request-Payload enthält die Änderung des Metadatenobjekts.
    • Die angegebenen Properties werden geändert.
    • Die übrigen Properties werden gelöscht, d.h. das existierende Metadatenobjekt wird vollständig ersetzt.
    • Falls das Metadatenobjekt nicht existiert, wird es neu angelegt.
  • Der Response-Payload enthält das geänderte Metadatenobjekt.
# Sammlung 'Personal' ändern
PUT /rest/test/schemes/Fachdatenmodell/collections/Personal

Mit PUT kann eine vorhandene Liste von Metadatenobjekten geändert werden:

  • Der technische oder fachliche Schlüssel der Liste von Metadatenobjekten ist in der URL kodiert.
  • Der Request-Payload enthält die Änderung der Liste von Metadatenobjekten.
    • Jedes existierende Metadatenobjekt, welches in der Liste vorkommt, wird geändert.
      • Die angegebenen Properties werden geändert.
      • Die übrigen Properties werden gelöscht, d.h. das existierende Metadatenobjekt wird vollständig ersetzt.
      • Falls ein Metadatenobjekt aus der Liste nicht existiert, wird es neu angelegt.
    • Jedes existierende Metadatenobjekt, welches in der Liste nicht vorkommt, wird gelöscht.
  • Der Response-Payload enthält die geänderte Liste von Metadatenobjekten.
# Liste von Enumerationen ändern
PUT /rest/test/schemes/Referenzdaten/enumerations

PATCH​

Mit PATCH kann ein vorhandenes Metadatenobjekt aktualisiert werden:

  • Der technische oder fachliche Schlüssel des Metadatenobjekts ist in der URL kodiert.
  • Der Request-Payload enthält die Aktualisierung des Metadatenobjekts.
    • Die angegebenen Properties werden aktualisiert.
    • Die übrigen Properties blieben unverändert, d.h. das existierende Metadatenobjekt wird nicht vollständig ersetzt.
    • Falls das Metadatenobjekt nicht existiert, wird es neu angelegt.
  • Der Response-Payload enthält das aktualisierte Metadatenobjekt.
# Sammlung 'Personal' aktualisieren
PATCH /rest/test/schemes/Fachdatenmodell/collections/Personal

Mit PATCH kann eine vorhandene Liste von Metadatenobjekten aktualisiert werden::

  • Der technische oder fachliche Schlüssel der Liste von Metadatenobjekten ist in der URL kodiert.
  • Der Request-Payload enthält die Aktualisierung der Liste von Metadatenobjekten.
    • Jedes existierende Metadatenobjekt, welches in der Liste vorkommt, wird aktualisiert.
      • Die angegebenen Properties werden aktualisiert.
      • Die übrigen Properties blieben unverändert, d.h. das existierende Metadatenobjekt wird nicht vollständig ersetzt.
      • Falls ein Metadatenobjekt aus der Liste nicht existiert, wird es neu angelegt.
    • Jedes existierende Metadatenobjekt, welches in der Liste nicht vorkommt, wird gelöscht, falls der Query-Parameter operation=REPLACE gesetzt ist (ansonsten werden obsolete Metadatenobjekte nicht gelöscht).
  • Der Response-Payload enthält die aktualisierte Liste von Metadatenobjekten.
# Liste von Enumerationen aktualisieren (obsolete Enumerationen behalten)
PATCH /rest/test/schemes/Referenzdaten/enumerations

# Liste von Enumerationen aktualisieren (obsolete Enumerationen löschen)
PATCH /rest/test/schemes/Referenzdaten/enumerations?operation=REPLACE

DELETE​

Mit DELETE kann ein vorhandenes Metadatenobjekt gelöscht werden:

  • Der technische oder fachliche Schlüssel des Metadatenobjekts ist in der URL kodiert.
  • Es gibt weder Request-Payload noch Response-Payload.
# Sammlung 'Personal' löschen
DELETE /rest/test/schemes/Fachdatenmodell/collections/Personal

Mit DELETE kann eine vorhandene Liste von Metadatenobjekten gelöscht werden:

  • Der technische oder fachliche Schlüssel der Liste von Metadatenobjekten ist in der URL kodiert.
  • Es gibt weder Request-Payload noch Response-Payload.
# Liste von Enumerationen löschen
DELETE /rest/test/schemes/Referenzdaten/enumerations

Zugriff über technischen Schlüssel​

Das REST/API erlaubt den Zugriff auf Metadatenobjekte über deren UUID (Universally Unique Identifier):

  • Mittels der UUID kann jedes Metadatenobjekt eindeutig (global und systemübergreifend) identifiziert werden.
  • Der Zugriff auf Metadatenobjekte mittels UUID erfolgt über den Pfad, der dem Typ des Metadatenobjekts entspricht.
    • Zum Beispiel, der Zugriff auf ein Attribute identifiziert durch <uuid> erfolgt über den Pfad /rest/attributes/<uuid>.
GET    /rest/test/attributes/1078f122-73a0-4996-90ed-ab4b7d6c0a9d
PUT    /rest/test/classifiers/9759a2a2-3d55-4517-bf21-323d823d8fff
PATCH  /rest/test/groups/fdd37002-f8b2-40d6-8832-80d1508944ca
DELETE /rest/test/attributes/0f125f21-f828-400a-a624-bdb26cf27806
Hinweis

Der Zugriff auf Metadatenobjekte mittels UUID kann selbst dann erfolgen, wenn der konkrete Typ des Metadatenobjekts unbekannt ist. Entsprechend der Hierarchie im Metamodell können auch allgemeinere Pfade verwendet werden. Zum Beispiel, ein Processing ist ein Activity und ein Activity ist ein Asset (laut Metamodell). Ein Processing identifiziert durch <uuid> kann daher nicht nur über den Pfad /rest/processings/<uuid> sondern auch über die allgemeineren Pfade /rest/activities/<uuid> oder /rest/assets/<uuid> abgefragt werden.

Zugriff über fachlichen Schlüssel​

Das REST/API erlaubt den Zugriff auf Metadatenobjekte über deren Bezeichnung (label):

  • Mittels der Bezeichnung (label) kann jedes Metadatenobjekt innerhalb der Objekthierarchie eindeutig identifiziert werden, d.h. ausgehend von einem Metadatenobjekt können alle untergeordneten Metadatenobjekte über deren Bezeichnung (label) adressiert werden.
  • Diese fachlichen Schlüssel können zu einem fachlichen Pfad zusammengesetzt werden, beginnend mit der obersten Ebene /schemes bzw. /organizations und davon ausgehend zu allen weiteren untergeordneten Metadatenobjekten.
GET    /rest/test/schemes/Fachdatenmodell
GET    /rest/test/schemes/Fachdatenmodell/attributedTo
GET    /rest/test/schemes/Fachdatenmodell/classifiers/Land
GET    /rest/test/schemes/Fachdatenmodell/classifiers/Land/attributes/ISO Code
POST   /rest/test/schemes/Fachdatenmodell/collections/Personal/classifiers
PUT    /rest/test/organizations/Organisation/persons/Mayer Walter
PATCH  /rest/test/organizations/Organisation
DELETE /rest/test/schemes/Fachdatenmodell/classifiers/Land/attributes/ISO Code

Format​

Das REST/API unterstützt die Übertragung von Daten in JSON:

  • Bei lesenden Zugriffen liefert das REST/API Metadatenobjekte im Format JSON Hypertext Application Language.
    • Die spezielle Property _type definiert den Typ des Metadatenobjekts.
    • Die spezielle Property _links enthält (entsprechend dem Entwurfsprinzip HATEOAS) alle URLs, welche der Aufrufer der REST-Schnittstelle zum weiteren Navigieren verwenden kann.
      • Die Property self enthält die URL zum Metadatenobjekt selbst.
      • Alle Beziehungen des Metadatenobjekts zu anderen (d.h. über- oder untergeordneten oder sonst wie in Beziehung stehenden) Metadatenobjekten werden in weiteren Properties innerhalb von _links abgebildet.
    • Die spezielle Property _embedded enthält (bei Abfragen die Listen zurückliefern) die Liste der entsprechenden Metadatenobjekte.
  • Bei schreibenden Zugriffen akzeptiert das REST/API Metadatenobjekte im Format JSON (ohne spezielle JSON/HAL-Properties).
    • Die spezielle Property _type definiert den Typ des Metadatenobjekts.

Beispiel: Abfrage eines einzelnen Attributs

Aufruf:
  GET /rest/test/schemes/Fachdatenmodell/classifiers/Land/attributes/ISO Code

JSON/HAL Response-Payload:
  {
      "_type": "BusinessAttribute",
      "id": "fc918bc8-4380-4299-8b52-b42b8b1bc806",
      "_version": 1,
      "tenant": "e2e5d8b6-da70-4985-b795-9cce4f13ce95",
      "createdBy": "admin",
      "dateCreated": 1624621433852,
      "db": "test",
      "description": "Der ISO Code des Landes referenziert einen Code aus dem Standard für die Kodierung von geographischen Einheiten (ISO 3166-1)",
      "label": "ISO Code",
      "modelId": "1078f122-73a0-4996-90ed-ab4b7d6c0a9d",
      "status": "WORKING",
      "title": "ISO Code des Landes",
      "hasDomain": "c342ba91-86ea-42c9-9218-177505fbca6e",
      "hasRange": "1dfce9fa-9815-4b06-a322-43999c4f5aaf",
      "identifying": true,
      "maxCardinality": 1,
      "minCardinality": 0,
      "required": "OPTIONAL",
      "cardinality": "ONE",
      "parentId": "c342ba91-86ea-42c9-9218-177505fbca6e",
      "href": "/web/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806",
      "_links": {
          "self": {
              "href": "/rest/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806"
          },
          "derivedTo": {
              "href": "/rest/test/attributes/fc918bc8-4380-4299-8b52-b42b8b1bc806/derivedTo"
          },
          "hasDomain": {
              "href": "/rest/test/classifiers/c342ba91-86ea-42c9-9218-177505fbca6e"
          },
          "hasRange": {
              "href": "/rest/test/enumerations/1dfce9fa-9815-4b06-a322-43999c4f5aaf"
          }
      }
  }

Beispiel: Abfrage einer Liste von Verantwortungen

Aufruf:
  GET /rest/test/schemes/Referenzdaten/attributedTo

JSON/HAL Response-Payload:
  {
      "total": 2,
      "_links": {
          "self": {
              "href": "/rest/test/schemes/22d6d683-3d59-46c7-a355-594a426ea309/attributedTo"
          }
      },
      "_embedded": {
          "attributedTo": [
              {
                  "id": "18d33dc6-b8ab-4991-80de-f5e07567af8a",
                  "attributionFor": "22d6d683-3d59-46c7-a355-594a426ea309",
                  "attributedTo": "ecae0cba-b800-4086-9fb2-c051aa5064a7",
                  "_links": {
                      "self": {
                          "href": "/rest/test/attributions/18d33dc6-b8ab-4991-80de-f5e07567af8a"
                      }
                  }
              },
              {
                  "id": "4ed01578-300b-4b72-98cc-df1fe4ae7d79",
                  "attributionFor": "22d6d683-3d59-46c7-a355-594a426ea309",
                  "attributedTo": "7644bdc0-f1e1-4bf4-a85a-8a0e72822389",
                  "_links": {
                      "self": {
                          "href": "/rest/test/attributions/4ed01578-300b-4b72-98cc-df1fe4ae7d79"
                      }
                  }
              }
          ]
      }
  }

Beispiel: Aktualisierung eines einzelnen Attributs

Aufruf:
  PATCH /rest/test/schemes/Fachdatenmodell/classifiers/Land/attributes/ISO Code

JSON Request-Payload:
  {
      "_type": "BusinessAttribute",
      "identifying": false
  }

Fehlerbehandlung​

Treten beim Verarbeiten der Daten in der Schnittstelle irgendwelche Fehler auf wird eine entsprechende Fehlermeldung zurückgesendet. Zusätzlich wird der HTTP-Statuscode der HTTP-Response gesetzt. Die Antwort enhält folgende Properties:

  • statusCode: HTTP-Statuscode
  • method: HTTP-Methode
  • message: Fehlermeldung (Beschreibung)
  • violations (optional): Liste aller verletzten Bedingungen (Constraints)
  • _links.self: URL des fehlerhaften Aufrufs

Beispiel: Abfrage eines nicht vorhandenen Modells

Aufruf:
  GET /rest/test/schemes/Unbekannt

JSON/HAL Response-Payload:
  {
      "statusCode": 404,
      "method": "GET",
      "message": "Modell *Unbekannt* konnte nicht gefunden werden!",
      "_links": {
          "self": "/rest/test/schemes/Unbekannt"
      }
  }

Beispiel: Anlage einer ungültigen Person

Aufruf:
  POST /rest/test/persons

JSON Request-Payload:
  {
      "_type": "Person",
      "familyName": "Mayer"
  }

JSON/HAL Response-Payload:
  {
      "statusCode": 400,
      "method": "POST",
      "message": "Person kann nicht angelegt werden!",
      "violations": [
          {
              "message": "*Vorname* muss angegeben werden!",
              "path": "givenName"
          },
          {
              "message": "*Organisation* muss angegeben werden!",
              "path": "agentOf"
          }
      ],
      "_links": {
          "self": "/rest/test/persons"
      }
  }