Hauptteil

Zugangskonzept

Die Zugriffe auf die WebAPI erfolgen auf Basis eines Benutzerkontos (NetDB-Konto) und eines zugeordneten Access Tokens. Alternativ kann auch noch der bisherige, in den Vorgängerversionen verwendete zertifikatsbasierte Zugang verwendet werden. Dieser wird allerdings zum 30.6.2021 endgültig deaktiviert.

Um das Risiko der Kompromittierung eines NetDB-Kontos zu minimieren und mögliche Einsatzprofile besser strukturieren zu können, gibt es 2 Arten von NetDB-Benutzerkonten:

Über ein Konto werden die Zugriffsrechte der ihm zugeordneten Access Token abgebildet. Unterkonten sind ausschließlich für den direkten WebAPI-Zugang vorgesehen und benutzen statische Token; Hauptkonten sind zur direkten Nutzung des Web-Portals (NETVS) vorgesehen und benutzen temporäre (Session-)Token. Unterkonten existieren nur in der NetDB und können vom Inhaber eines Hauptkontos jederzeit nach eigenem Ermessen angelegt, modifiziert oder gelöscht werden. Jedem Unterkonto (und den zugehörigen Access Token) ist dadurch genau ein Hauptkonto zu- und übergeordnet. Ebenso kann der Inhaber des Hauptkontos im Rahmen seiner eigenen Rechte auch die Rechte seiner Unterkonten (Rollen, Untergruppen, ND-Modultypklassen, ND-Accessgruppen) verwalten. Zusätzlich kann ein Unterkonto als ‘Nur-Lese-Konto’ eingestellt werden. Dadurch ist der Zugriff auf datenmodifizierende WebAPI-Funktionen gesperrt. Diese Sperre hat Vorrang vor allen anderen Rechten und wirkt davon unabhängig. Auch diese Einstellung kann der Inhaber des Hauptkontos jederzeit für alle seine Unterkonten ändern.

Unterkonten haben eine funktionale Sperre für

Diese Sperre wirkt unabhängig davon, ob das Unterkonto tatsächlich die benötigten Rechte hat. Die gesperrten Funktionen können daher nur mittels Hauptkonto ausgeführt werden. Unterkonten dürfen nur ihre eigenen Access-Token modifizieren.

Gruppen und Konten für Bereichsbetreuer

Gruppen dienen der effizienten Zuordnung der Netzbereiche (Adressräume, Namensräume) zu Benutzerkonten. Einer Gruppe sind BCDs, Domains und Benutzerkonten zugeordnet. Die zugeordneten Benutzerkonten werden auch als Gruppenmitglieder bezeichnet. Den Gruppenmitgliedern sind somit Domains und BCDs zugeordnet. Analog zu den beiden Kontenarten gibt es auch 2 Arten der Gruppen:

Domain- und BCD- Zuordnungen in Untergruppen können nur im Rahmen vorhandener Zuordnungen ihrer Hauptgruppe bestehen.

Hauptgruppen in der NetDB können in 2 Modi benutzt werden:

Wird ein KIT-Benutzerkonto einer Hauptgruppe im IDM zugeordnet, und möchte der Kontoinhaber eine eigene Untergruppe mit eigenen Unterkonten erstellen, kann er dies erst, nachdem die Hauptgruppe synchronisiert wurde (und die Gruppenmitglieder aktualisiert sind). Umgekehrt werden Untergruppen und deren Unterkonten automatisch aus einer Hauptgruppe entfernt, wenn auch ihr Hauptkonto aus der Hauptgruppe entfernt wurde (unabhängig davon, ob die Hauptgruppe IDM-synchron ist oder nicht). Die automatische Synchronisation erfolgt dabei nicht in Echtzeit, sondern stündlich für alle Gruppen. Sie kann aber auch jederzeit explizit für eine bestimmte Gruppe angefordert werden, um eine sofortige Synchronisation zu erreichen. Der Synchronisationsvorgang ist IDM-seitig nur-lesend; alle Schreibzugriffe erfolgen ausschließlich NetDB-seitig.

Gruppenadministration durch OE-Betreuer

Für die Gruppenadministration ist die Zuordnung eines Benutzerkontos zu einer Organisationseinheit (OE) erforderlich. Diese Zuordnung wird nicht vom IDM übernommen, sondern primär in der NetDB abgebildet. Der Inhaber des zugeordneten Kontos wird dadurch OE-Betreuer und bekommt das Administrationsrecht für alle Hauptgruppen, die seiner OE (oder einer darunterliegenden OE, dh. seinem OE-Teilbaum) zugeordnet sind. Ebenso bekommt er das Administrationsrecht für alle Domains und BCDs, deren OEs seinem OE-Teilbaum zugeordnet sind. Zusammengefasst:

Das Administrationsrecht für Hauptgruppen, deren OE im eigenen OE-Teilbaum liegt, umfasst außerdem:

Untergruppen werden ausschließlich durch ihre Eigentümer administriert.

Gruppenduplikate

Für die Zuordnungen in Gruppen (BCDs, Domains, Konten) gelten die folgenden Eindeutigkeitsregeln.

Hauptgruppen

Mehrere Hauptgruppen im gleichen OE-Zweig (dh. deren OEs einander über- oder untergeordnet sind) mit identischer Domainliste und identischer Kontenliste sind nicht erlaubt, da sich dann die BCD-Listen dieser Gruppen auch in einer Gruppe zusammenfassen ließen. Die verbleibenden Varianten mit

entfallen, weil eine BCD nicht mehreren Gruppen zugeordnet sein kann.

Untergruppen

Mehrere Untergruppen eines Eigentümers mit

sind nicht erlaubt, da sich dann die jeweils nicht genannten Listen dieser Gruppen auch in einer Gruppe zusammenfassen ließen. Erlaubt sind sie jedoch, wenn sie unterschiedliche Eigentümer haben.

Automatische Zusammenfassung entstehender Gruppenduplikate

Wenn durch Eintragen oder Löschen eines Elements der o.g. Listen (Konten, Domains, BCDs) einer Gruppe Duplikate entstehen und wenn für diese Gruppe die Einstellung “Gruppenduplikate automatisch zusammenfassen” (Parameter do_mdg, merge duplicate groups) aktiviert ist, werden die Duplikate so zusammengefasst, dass diese Gruppe am Ende übrigbleibt. Das Ergebnis und der Zeitstempel dieser automatischen Zusammenfassung ist in den Attributen mdg_last_result und mdg_last_ts hinterlegt.

Authentifizierung

WebAPI-Zugriffe (Requests) werden über ein token-basiertes Verfahren authentifiziert. Dazu kann jedem Unterkonto ein oder mehrere sog. Access Token zugeordnet werden. Über diese Zuordnung erfolgt die Identifikation. Der WebAPI-Zugriff erfolgt also mit den Rechten des Kontos, das dem verwendeten Access Token zugeordnet ist. Das Token bzw. der Token-Text wird vom System (NetDB) automatisch generiert und ist sicherheitstechnisch wie ein Klartext-Passwort zu betrachten.

Die Registrierung eines Tokens muss je nach Umgebung über die NETVS-Webseite

vorgenommen werden.

Ein Access Token umfasst folgende Hauptdaten:

Statische Token werden für den WebAPI-Zugriff der Unterkonten verwendet. Der Inhaber des Hauptkontos kann für statische Token seiner Unterkonten jederzeit einen neuen Token-Text vom System generieren lassen, ebenso kann er das Ablaufdatum und den Beschreibungstext jederzeit neu bestimmen oder das Token löschen. Abgelaufene Token werden nach weiteren 200 Tagen automatisch gelöscht. Wichtig: statische Token ohne Ablaufdatum werden auch gelöscht, nachdem sie 200 Tage unbenutzt waren. Um dies zu verhindern, empfehlen wir, rechtzeitig eine Re-Validierung durch z.B. einen Request mit leerer Transaktion auszuführen.

Temporäre Token werden typischerweise für Web-Browser-Sessions der Hauptkonten verwendet. Deren Ablaufdatum wird bei jedem Zugriff um das festgelegte Intervall verlängert. Der Inhaber des Hauptkontos kann eigene temporäre Token jederzeit löschen. Abgelaufene Token werden täglich automatisch gelöscht.

Hinweise zur Registrierung von Unterkonten

Wir empfehlen Ihnen aus Sicherheitsgründen (Schadensminimierung im Mißbrauchsfall):

Hinweise zur Token-Benutzung

Der Token-Text ist das Identifizierungsmerkmal des eindeutig zugeordneten Benutzerkontos. Der Besitzer des Token-Textes kann hierdurch WebAPI-Requests mit den Rechten des zugeordneten Kontos ausführen. Um einen Mißbrauch bzw. Kompromittierung zu vermeiden, beachten Sie bitte folgendes:

URI-Schema

Alle Zugriffe (Requests) werden über URIs adressiert, deren Aufbau nach folgendem Schema erklärt wird:

<BASE-URI>/<ROOT>/<vmajor>.<vminor>/<sys>/<objtype>/<function>[<params>]

<BASE-URI>: https://www-net.scc.kit.edu       "Produktionsumgebung"
            https://www-net-test.scc.kit.edu  "Testumgebung (täglich veraltete Kopie der Produktionsumgebung)"
            https://www-net-devel.scc.kit.edu "Entwicklungsumgebung (unbestimmt veraltete Kopie der Produktionsumgebung mit Modifikationen)"

<ROOT>    : api
<vmajor>  : "natürliche Zahl, Hauptnummer der Version (Versionsreihe, Major Release)"
<vminor>  : "natürliche Zahl, Unternummer der Version innerhalb der Versionsreihe (Minor Release)"

<sys>     : "WebAPI-Systemname, Teilbereich von Anwendungsdaten (z.B. dns, nd)"
<objtype> : "WebAPI-Objekttyp-Bezeichnung (z.B. record, module, fqdn)"
<function>: "WebAPI-Funktion: Zugriffsart (z.B. create, update, delete, list)"

<params>  : "Parameterzeichenkette (query string) der Form ?<param1>=<value1>[&<param2>=<value2>[&...]]"

Alle rechtsseitig bzw. unterhalb von <ROOT> stehenden Platzhalter im URI-Schema sind demnach variabel. Ihre Wertebelegungen sind bei Versionswechseln als potentiell veränderbar zu betrachten und können daher versionsweise unterschiedlich sein. Eine Ausgabe der Wertebelegungen der variablen Platzhalter kann über Indexabfragen oder über die Ausgabe (list-Funktion) der Objekttypen “/wapi/system”, “/wapi/object_type”, “/wapi/function” erreicht werden.

Die Inhalte der drei angegebenen Datenbanken (Produktions-, Test- und Entwicklungsumgebung) sind für sich unabhängig voneinander, aber:

Deren Datenbestände sind also “Momentaufnahmen” der Produktionsdatenbank und grundsätzlich als veraltet anzusehen. Demnach müssen auch ggf. neue Konto- bzw. Token-Registrierungen, die sofort auch in Test- und Entwicklungsumgebung benötigt werden, dort separat vorgenommen werden.

Requests

Ein Request entspricht einer Datenbank-Transaktion.

Authentifizierung

Im HTTP-Header Authorization muss ein gültiges OAuth 2.0 Bearer Token übergeben werden. Muster des HTTP-Headers:

Authorization: Bearer ***AUTH-TOKEN-TEXT***

Bearer bezeichnet das Authentifizierungsschema; ***AUTH-TOKEN-TEXT*** ist der exakte Text des Access-Tokens. Zwischen beiden Angaben steht mindestens 1 Leerzeichen.

Jedes Access-Token ist genau einem Benutzerkonto zugeordnet, dessen Rechte bei der Ausführung des Requests gelten.

Unterstützte Methoden

Als HTTP-Request-Methoden können POST (generell) und GET (nur für nicht-datenmodifizierende Funktionen) verwendet werden. Als Zeichenkodierung wird ausschließlich UTF-8 verwendet. Zur Ablehnung des Requests führen:

POST-Request

Diese Methode bietet die volle Funktionalität und ist für alle Funktionsaufrufe verwendbar. Der Request Body muss ein gültiges JSON-Dokument sein und auch als solches deklariert sein (HTTP-Header: Content-Type:application/json). Ein ungültiges JSON-Dokument führt zur Ablehnung des Requests.

Requests als Einzelbefehls-Aufruf

Bei dieser Variante wird pro Request genau ein Objekt eines Objekttyps eines Systems mit einer Funktion behandelt. Sollen mehrere Objekte desselben Objekttyps und Systems mit derselben Funktion behandelt werden, ist pro Objekt ein separater Request erforderlich; es sei denn, die Funktion gestattet die Behandlung mehrerer Objekte (Bulk-Funktion). URI-Schema unterhalb der Version:

/<sys>/<objtype>/<function>

Datenstruktur des Request Body:

Da System, Objekttyp und Funktion bereits im URI adressiert sind, besteht das JSON-Dokument nur aus einem JSON-Dict mit den Bezeichnern old, new für die jeweiligen Parameter-Wertebelegungen. old beinhaltet die jeweiligen Parameterwerte vor der Änderung; new diejenigen nach der Änderung:

{
  "old": {
    "<param_name>": <param_value>, ...
  },
  "new": {
    "<param_name>": <param_value>, ...
  }
}

Requests als Mehrfachbefehls-Aufruf / Ausgaben im relationalen Verbund (JOIN)

Pro Request können hier mehrere Befehle (Statements) mit jeweils unterschiedlichen Systemen, Objekttypen und Funktionen behandelt werden. URI-Schema unterhalb der Version:

/wapi/transaction/execute

Im Gegensatz zum Einzelbefehls-Aufruf sind System, Objekttyp und Funktion hier nicht im URI festgelegt, sondern werden im Request Body pro Statement angegeben. Bei diesem generischen Transaktionsaufruf kann zusätzlich in der Parameterzeichenkette der Steuerparameter dry_mode (Boolean-Typ) verwendet werden.

Datenstruktur des Request Body

Da mehrere Statements möglich sind, besteht das JSON-Dokument aus einem äußeren JSON-Array, das die Transaktionsebene darstellt. Dieses enthält wiederum JSON-Dicts, welche jeweils ein Statement darstellen. Der Statement-Index entspricht der Statement-Position und ist immer 0-basiert, d.h. die Position des ersten JSON-Dicts ist 0. Pro Statement müssen neben der Parameter-Wertebelegung auch die jeweiligen Werte für System, Objekttyp und Funktion unter dem Bezeichner name explizit angegeben werden. Unter dem Bezeichner join kann optional ein Verbund mehrerer Statement-Ausgaben als JSON-Dict angegeben werden (nur, wenn der Statement-Index größer als 0 ist und nur bei Funktionen, die nicht datenmodifizierend sind).

Die Parameter-Wertebelegung kann in 2 Varianten erfolgen:

[
  {
    "name": "<system_name>.<object_type_name>.<function_name>",
    "old": {
      "<param_name>": <param_value>
    },
    "old_ref": {
      "<param_name>": { "idx": <ref_stmt_idx>, "param": "<ref_param_name>", "allow_no_data": true | false }
    },
    "new": {
      "<param_name>": <param_value>
    },
    "new_ref": {
      "<param_name>": { "idx": <ref_stmt_idx>, "param": "<ref_param_name>", "allow_no_data": true | false }
    },
    "join": {
      "<join_stmt_idx>": "<ref_constraint_name>" | null
    }
  }
]

Pro Statement und Parametername ist entweder Variante 1 oder Variante 2 verwendbar, d.h. ein Parametername darf nicht gleichzeitig als Bezeichner in old und old_ref oder in new und new_ref vorkommen. Parameternamen sollten nur einmal pro Belegung vorkommen. Andernfalls werden Werte von Parameternamen (die mehrfach in derselben Belegung vorkommen) überschrieben, so dass nur einer dieser Werte für den Parameter übernommen wird. Dies kann zu unerwünschten Ergebnissen oder zur Ablehnung des Requests führen.

Ausgabe von Objekten relational verbundener Objekttypen im Statement-Verbund mit join

Um relevante Ausgabedaten referenzierender oder referenzierter Objekte zu erhalten (und die Datenmenge besser einzugrenzen), kann die Ausgabe eines (nachfolgenden) Statements mit der Ausgabe eines oder mehrerer (nicht zwingend direkt) vorausgehenden Statements verbunden werden. Verbund bedeutet, dass zwischen den Objekttypen dieser beiden Statements eine Relation besteht (referenzierender oder Foreign Key Constraint). Dabei werden nur diejenigen Objekte des nachfolgenden Statements ausgegeben, deren referenzierbare (bzw. referenzierte) Attributwerte mit denen des vorausgehenden Statements übereinstimmen. Der Verbund wird dabei über den Index des vorausgehenden Statements und -außer bei Log-Ausgaben- den Namen des referenzierenden Constraints (s. Abschnitt Objekttypen) definiert. Das nachfolgende Statement hat dabei einen Index > 0, und dessen Funktion ist nicht datenmodifizierend. Der Index des vorausgehenden Statements ist kleiner als der des nachfolgenden Statements. Im JSON-Dict des Bezeichners (Schlüssel) join ist <join_stmt_idx> der Index des vorausgehenden Statements, und <ref_constraint_name> (Wert zum Schlüssel) entweder der Constraint-Name oder null, je nach Variante. Es gibt 2 Verbundvarianten:

  1. Constraint-basiert: Zwischen den Objekttypen des vorausgehenden und nachfolgenden Statements existiert ein referenzierender Constraint (Typ “f”), dessen Name im JSON-Dict des Bezeichners join als Wert für <ref_constraint_name> (zum Dict-Schlüssel <join_stmt_idx>) angegeben werden muss. Der Constraint gehört entweder zum Objekttyp des vorausgehenden oder des nachfolgenden Statements. Es können nur Constraints verwendet werden, die in der jeweiligen Objekttypdefinition unter referencing oder referenced_by existieren. Im nachfolgenden Statement werden dadurch nur Objektdatensätze ausgegeben, die entsprechend des angegebenen Constraints zu Objekten des vorausgehenden Statements gehören. Die Zugehörigkeit der Objektdatensätze dieser beiden Verbund-Statements wird über die Wertegleichheit der jeweiligen (Objekttyp-)Attribute des referenzierenden Constraints und des referenzierten Constraints hergestellt. Die Ausgabe des vorausgehenden Statements wird davon nicht beeinflusst.
  2. Log-basiert: Der Objekttyp des nachfolgenden Statements gehört zur Kategorie “Log-Datensenke”, und der Objekttyp des vorausgehenden Statements gehört zur Kategorie “Log-Datenquelle”. Der Wert zum Dict-Schlüssel <join_stmt_idx> ist null. Im nachfolgenden Statement werden alle Log-Datensätze ausgegeben, die zu Objekten des vorausgehenden Statements gehören. Die Zugehörigkeit der Objektdatensätze dieser beiden Verbund-Statements wird über die Wertegleichheit des Attributs log_fk (auf Seite der Log-Datensenke) und des Attributs log_pk (auf Seite der Log-Datenquelle) hergestellt. Die Ausgabe des vorausgehenden Statements wird davon nicht beeinflusst.

Alle Schlüssel-Wert-Paare, die im Join-Dict vorhanden sind, werden funktional logisch-UND verknüpft.

GET-Request

Diese Methode kann nur für nicht-datenmodifizierende Funktionen als Einzelbefehls-Aufruf verwendet werden. Im Funktionsindex sind diese durch das Attribut is_data_manipulating mit dem Wert false gekennzeichnet. Die Parameterzeichenkette (query string) entspricht hierbei der Belegung unter old im Parameterverzeichnis des Funktionsindex. Da die Parameterzeichenkette kein JSON-Format hat, werden die Parameterwerte nach JSON konvertiert; d.h. der Parameterwert wird als JSON-Literal betrachtet und daraus der entsprechende JSON-Datentyp abgeleitet. Dabei ergeben sich folgende Besonderheiten:

Alle Parameterwerte haben durchweg auswählenden Charakter und werden typischerweise logisch-UND verknüpft. Elemente in Parameterwerten des JSON-Datentyps array werden typischerweise logisch-ODER verknüpft. Parameternamen dürfen nur einmal in der Parameterzeichenkette vorkommen; andernfalls werden deren Werte als Array gepackt übergeben und dadurch fälschlicherweise als Array-Literal interpretiert, was zu unerwünschten Ergebnissen oder zur Ablehnung des Requests führen kann. Parameterwerte, die reservierte URI-Zeichen enthalten, müssen kodiert werden (Stichworte ‘Prozentkodierung’, ‘URL-Encoding’, s.a. https://de.wikipedia.org/wiki/URL-Encoding).

Antwortverhalten der Funktionen

Es gibt 2 Kriterien, nach denen das Antwortverhalten eingeteilt wird:

  1. Rückgabefähigkeit: darunter wird die Eigenschaft einer Funktion verstanden, ihre Ergebnisdaten als nicht-leere oder leere Antwort zurückzugeben. Trifft dies nicht zu, wird garantiert eine leere Antwort zurückgegeben. (s. Funktionsattribut is_returning)

  2. Referenzierbarkeit: darunter wird die Eigenschaft einer Funktion verstanden, garantiert eine nicht-leere Antwort mit genau einem Ergebnisdatensatz zurückzugeben. Dadurch ist sie referenzierbar, dh. sie speichert den Ergebnisdatensatz für die Dauer der Transaktion, so dass er von nachfolgenden Funktionen innerhalb derselben Transaktion als Eingabewert verwendet (referenziert) werden kann. (s. Funktionsattribut is_returning_referenceable)

Nicht-datenmodifizierende Funktionen (s. Funktionsattribut is_data_manipulating) sind typischerweise immer rückgabefähig, aber nicht referenzierbar und geben im Normalfall an ihrem Statement-Index ein JSON-Array zurück, das die Ergebnisdatensätze entsprechend des angeforderten Objekttyps und der Abfragekriterien (auswählende Eingabeparameter) enthält. Bei Nichtzutreffen der Abfragekriterien bzw. falls keine übereinstimmenden Daten des Objekttyps vorhanden sind, wird eine leere Liste (leere Antwort) zurückgegeben. Die Referenzierbarkeit ist hier dynamisch und hängt von der Anzahl der Objekttyp-Datensätze in der Funktionsantwort des betreffenden Statement-Index ab. Falls genau 1 Objekt-Datensatz zurückgegeben wird, ist die Funktion an diesem Statement-Index dadurch automatisch referenzierbar (analoges Verhalten zu referenzierbaren Funktionen). Durch die Abfrage von Schlüsselparametern eines Objekttyps (zugeordnete Constraint-Typen: Primärschlüssel (p) oder Schlüssel (u)) kann hier die Referenzierbarkeit vorbestimmt werden (Schlüsselparameter erzwingen genau einen Objekt-Datensatz, falls er existiert.)

Antwort-Datenstruktur bei fehlerfreier Transaktion

Die Antwort ist immer ein JSON-Dokument mit folgendem Aufbau (von außen nach innen):

Antwort-Datenstruktur im Fehlerfall (Exception, Transaktionsabbruch)

Zusätzlich zum HTTP-Statuscode (4xx) wird ein JSON-Dict zurückgegeben, dessen (einziger) Key exception wiederum ein Dict mit der Struktur des Objekttyps wapi.exception enthält. Muster:

{
  "exception": {
    "error": {
      "code": number,
      "description": "text",
      "details": "text"
    },
    "error_type": {
      "code": number,
      "name": "text",
      "description": "text"
    },
    "constraint": {
      "name": "text",
      "description": "text"
    },
    "others": {},
    "stacked_diag_params" {
      "column": "text",
      "constraint": "text",
      "context": "text",
      "datatype": "text",
      "detail": "text",
      "dml_src_table": "text",
      "hint": "text",
      "message": "text",
      "schema": "text",
      "sqlstate": "text",
      "table": "text"
    },
    "traceback": [
      {
        "function": "text",
        "param": {
          "<param_name1>": <param_value1>,
          "<param_name2>": <param_value2>,
          ...
        }
      },
      ...,
      {
        "function": "wapi_3_0.exec_ta_handler",
        "param": {
          "wapi.transaction_stmt.index": number
        }
      }
    ]
  }
}

Indexabfragen

Die Indexabfragen erlauben es, die gültigen Wertebelegungen der jeweils nächsten Unterebene des URI-Schemas festzustellen. Merkmal für Indexabfragen ist der endende Schrägstrich / (Slash). Optional kann das Schlüsselwort index nach dem Slash ergänzt werden, dies hat aber keine Auswirkungen. Indexabfragen sind parameterlos. Intern sind sie eine Weiterleitung auf den entsprechenden Objekttyp im Systemdatenbereich unter /wapi.

Für die 4 Unterebenen gilt folgendes allgemeines Schema:

Versionsindex : <BASE-URI>/<ROOT>/
Systemindex   : <BASE-URI>/<ROOT>/<vmajor>.<vminor>/
Objekttypindex: <BASE-URI>/<ROOT>/<vmajor>.<vminor>/<sys>/
Funktionsindex: <BASE-URI>/<ROOT>/<vmajor>.<vminor>/<sys>/<objtype>/

Dazu die äquivalenten Systemdatenabfragen entsprechend der internen Weiterleitung (außer Versionsindex):

Systemindex   : <BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/system/list
Objekttypindex: <BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/object_type/list?system_list=["<sys>"]
Funktionsindex: <BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/function/list?system_list=["<sys>"]&object_type_list=["<objtype>"]

Beispiele:

Abfragen der Systemdaten

Für den Systemdatenbereich ist das Spezial-System /wapi vorgesehen. Unterhalb dieses Systems sind Basis-Objekttypen für

definiert. Diese liefern Informationen über alle weiteren Systeme, Objekttypen und Funktionen.

Allgemeine Objekttyp-Datenstruktur

Jeder Objekttyp wird nach folgendem Schema dargestellt:

{ 
  "attributes": {
    "<attribute_name>": {
      "data_type": "<api_datatype_name>",
      "json_data_type": "<json_datatype_name>",
      "description_detail": "detaillierter Beschreibungstext des Attributes",
      "description_obj_type_scope": "objekttyp-weite Beschreibung des Attributes",
      "description_sys_scope": "system-weite Beschreibung des Attributes",
      "is_core": true | false,
      "is_nullable": true | false,
      "supported_values": {
        "<value>": "<value_description>"
      }
    }
  },
  "constraints": {
    "<constraint_name>": {
      "type": "<constraint_type>",
      "grants_read_access": true | false,
      "is_deferred": true | false,
      "internal_name": "systeminterner Name des Constraints",
      "description": "Beschreibungstext des Constraints",
      "errors": [
        {
          "code": <error_code>,
          "type": <error_type_code>,
          "description": "<error_description>",
          "details": "<error_details>"
        }
      ]
    }
  },
  "description_abbrev": "Abkürzung des Objekttyps",
  "description_detail": "ausführlicher Beschreibungstext des Objekttyps",
  "description_title": "Titeltext des Objekttyps",
  "fq_name": "<system_name>.<object_type_name>",
  "is_log_dst": true | false,
  "is_log_src": true | false,
  "name": "<object_type_name>",
  "referenceable": {
    "<constraint_name>": {
      "attributes": [ "<attribute_name>" ],
      "is_deferred": true | false,
      "referenced_by": [ {"system": "<system_name>", "object_type": "<object_type_name>", "name": "<constraint_name>"} ],
      "type": "<constraint_type>"
    }
  },
  "referencing": {
    "<constraint_name>": {
      "attributes": [ "<attribute_name>" ],
      "is_deferred": true | false,
      "on_delete": "raise" | "cascade" | "set null" | "set default",
      "references": {"system": "<system_name>", "object_type": "<object_type_name>", "name": "<constraint_name>"}
    }
  },
  "system": "<system_name>"
}

Bedeutung der Platzhalter (Variablen):

Bedeutung der Bezeichner (Konstanten):

Beispiel

Allgemeine Funktions-Datenstruktur

Parameter bzw. Objekttyp-Attribute, die nicht-ausführbaren Funktionen zugeordnet sind, sind nur im Objekttypindex, aber nicht im Funktionsindex sichtbar. Jede ausführbare Funktion eines Objekttyps wird nach folgendem Schema dargestellt:


{
  "fq_name": "<system_name>.<object_type_name>.<function_name>",
  "is_data_manipulating": true | false,
  "is_executable": true | false,
  "is_returning": true | false,
  "is_returning_referenceable": true | false,
  "name": "<function_name>",
  "object_type": "<object_type_name>",
  "parameters": {
    "<parameter_name>": {
      "data_type": "<api_datatype_name>",
      "json_data_type": "<json_datatype_name>",
      "description_detail": "detaillierter Beschreibungstext des Parameters",
      "description_obj_type_scope": "objekttyp-weite Beschreibung des Parameters",
      "description_sys_scope": "system-weite Beschreibung des Parameters",
      "old": {
        "data_default": <default_value>,
        "is_nullable": true | false,
        "is_required": true | false
      },
      "new": {
        "data_default": <default_value>,
        "is_nullable": true | false,
        "is_required": true | false
      },
      "supported_values": {
        "<value>": "<value_description>"
      }
    }
  },
  "system": "<system_name>"
}

Bedeutung der Platzhalter (Variablen):

Bedeutung der Bezeichner (Konstanten):

Je nach Funktion ist die Wertebelegung für old und/oder new definiert; mindestens aber eine davon. Die jeweils nicht definierte Wertebelegung wird weggelassen. Für Nur-Lesefunktionen ist immer die Altbelegung definiert.

Beispiel

Versionsangaben

Die explizite Versionsangabe aller Zugriffe ermöglicht es, neue Features schnell einzuführen, ohne Clients, die eine bestehende Version benutzen, auszusperren oder auf deren Versionsanpassung zu warten. Die Hauptnummer wird bei umfangreichen API-Änderungen erhöht, die Anpassungen bei den meisten Clients erfordern würden; die Unternummer bei solchen, die die meisten Clients nicht betrifft.

Beide Versionsangaben (<vmajor>, <vminor>) sind numerisch (natürliche Zahl). Um den Status einer Version zu kennzeichnen, gibt es neben der numerischen Versionsangabe (Standard-Angabe) auch eine semantische Angabe. Sie bezieht sich auf die Version der internen Schnittstelle zwischen WebAPI und der darunterliegenden Datenbank (NetDB). Die Versionsangabe bei Requests kann nur numerisch sein. Beispiele für den Status einer Version (semantische Versionsangaben):

Beispiel-Szenarium für einen Versionswechsel