Hauptteil

URI-Schema

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

  • Werte in spitzen Klammern sind Platzhalter
  • Werte in eckigen Klammern sind optional
  • großgeschriebene Platzhalter sind konstant; kleingeschriebene sind variabel
  • Beschreibungstext wird von Anführungszeichen "" umgeben
<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)"

<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, fqdn)"
<function>: "WebAPI-Zugriffsart (Funktion): Eingabe (Datenmanipulation, z.b. create, update, delete) oder Ausgabe (z.b. list)"

<params>  : "Parameter-Zeichenkette 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 Standard-Indexabfragen erreicht werden. Die Änderungen der Wertebelegungen zwischen verschiedenen Versionen können über Indexabfragen zum Versionsvergleich abgefragt werden.

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

  • die Testdatenbank wird täglich nachts von der Produktionsdatenbank kopiert. Dort gemachte Änderungen sind also maximal für einen Tag sichtbar, weil sie anschließend wieder vom Stand der Produktionsdatenbank überschrieben werden.
  • Die Entwicklungsdatenbank wird in unregelmäßigen Abständen von der Produktionsdatenbank kopiert.

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

Parameter-Zeichenkette (GET-Request)

Parameter für den Funktionsaufruf, die auswählenden Charakter haben, werden in der Parameter-Zeichenkette des URI als GET-Request übergeben. Parameternamen sind groß/kleinschreibungs-unterscheidbar (case sensitive) und beschränkt auf die Zeichen [A-Za-z0-9_] (mit weiteren Einschränkungen). Namen, die mit einem Unterstrich _ (Underscore) beginnen, bezeichnen Parameter, die nicht öffentlich dokumentiert werden. Ihre Bedeutung kann sich jederzeit unangekündigt ändern, ohne dass die API-Version erhöht wird. Parameterwerte sind grundsätzlich UTF-8-kodiert zu übergeben; nicht als UTF-8 dekodierbare Werte führen zur Ablehnung des gesamten Requests. Parameterwerte, die reservierte URI-Zeichen enthalten, müssen kodiert werden (Stichworte ‘Prozentkodierung’, ‘URL-Encoding’, s.a. https://de.wikipedia.org/wiki/URL-Encoding). Die Übergabe von Parametern, die die jeweilige Funktion nicht erwartet, führt zur Ablehnung des Requests. Parameter, die eine Liste von Werten erwarten, sind entsprechend mehrfach zu übergeben. Typischerweise bilden Listen von auswählenden gleichnamigen Parameterwerten eine ODER-Verknüpfung (innerhalb des Parameters); dagegen werden auswählende nichtgleichnamige Parameterwerte UND-verknüpft. Die mehrfache Übergabe von Parametern, die genau einen Wert erwarten, führt zur Ablehnung des Requests. Boolean- Parameter sind als Zeichenkette true oder false, Groß-/Kleinschreibung egal, zu übergeben. Andere Werte führen zur Ablehnung des Requests.

Request Body (POST-Request)

Der Request Body muß bei Dateneingabefunktionen ein gültiges JSON-Dokument sein und auch als solches deklariert sein (Content-Type:application/json). Er wird typischerweise als POST-Request gesendet und dient der Übertragung von Eingabedaten bzw. Transaktionsdaten für Datenmanipulationen. Es wird ausschließlich UTF-8 verwendet; nicht als UTF-8 dekodierbare Werte führen zur Ablehnung des gesamten Requests. Dateneingabefunktionen sind im Funktionsindex-Abfragebeispiel durch den Bezeichner "mode" mit dem Wert bzw. Listenelement "write" erkennbar.

Bei Datenausgabefunktionen gelten für den Inhalt des Request Body die gleichen Regeln wie für die Parameter-Zeichenkette des URI.

Requests zur Datenausgabe

Sämtliche Requests für Datenausgaben funktionieren (auch) ohne Übertragung eines Request Body. Alle für die Spezifikation der auszugebenden Daten erforderlichen Parameter können wahlweise in der Parameterzeichenkette (GET-Request) oder im Request Body (POST-Request) übergeben werden. Das Antwortformat ist JSON, und als Zeichenkodierung wird ausschließlich UTF-8 verwendet. Datenausgabefunktionen sind im Funktionsindex-Abfragebeispiel durch den Bezeichner "mode" mit dem Wert bzw. Listenelement "read" erkennbar. Desweiteren gehören alle Indexabfragen dazu, die jedoch nicht im Funktionsindex erscheinen.

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.

Standard-Indexabfragen

Standard-Indexabfragen sind parameterlos. 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>/

Im Funktionsindex sind folgende Funktionsmodi durch den Bezeichner "mode" (unterhalb des Funktionsbezeichners) unterscheidbar:

  • "read": Abfrage- bzw. Datenausgabefunktionen. Ihre Funktionsparameter sind unter dem Bezeichner "params_dict" vorhanden. Verfügbare Beschreibungsattribute wiederum unter den Funktionsparametern sind
    • "default": Standardwert
    • "description": Parameterbeschreibung
    • "supported_values": falls der Parameter einen fest definierten Wertesatz hat
  • "write": Funktionen zur Dateneingabe/Datenmanipulation.
    • Die Datenstruktur ihrer Eingabeparameter (für den Request Body als POST-Request) ist nur über das Systemdatenverzeichnis abfragbar, da sie grundlegend anders strukturiert sind als die der Datenausgabefunktionen.
    • Die Datenstruktur ihrer Rückgabeparameter ist (stellvertretend) inspizierbar über wapi/transaction/list_datastructure?function_name=run
  • "inspectable": Die Datenstruktur ihrer Ausgabe ist über die jeweilige (dem selben Objekttyp zugeordnete) "inspect"-Funktion abfragbar.
  • "inspect": Funktionen zur Ausgabe der Datenstruktur von "inspectable"-Funktionen (des selben Objekttyps)
  • "ta_modify": Funktionen zur Manipulation von Transaktions-Plänen (leere Rückgabe)
  • "ta_execute": Ausführungsfunktionen für Transaktions-Pläne (Rückgabe wie "write")

Beispiele:

Indexabfragen zum Versionsvergleich

Bei einem bevorstehenden Versionswechsel ist es nützlich, Unterschiede zwischen der ursprünglichen (Quell-) und der neuen (Ziel-) Version feststellen zu können. Als ursprüngliche wird die über den URI adressierte Version bezeichnet; als neue wird die durch einen separaten Parameter angegebene Version bezeichnet. Die Ausgabe erfolgt, indem vor jedes Dict-Objekt der Indexausgabe ein weiteres zur Einteilung in 4 Änderungskategorien geschaltet wird. Deren Bezeichner lauten:

  • "+": hinzugekommene Dict-Objekte (Schlüssel)
  • "-": nicht mehr vorhandene Dict-Objekte (Schlüssel)
  • "<>": veränderte Dict-Objekte, d.h. bei gleichem Schlüssel hat sich der Wert bzw. Inhalt geändert
    • "<": alter Wert bzw. Inhalt des geänderten Dict-Objektes
    • ">”: neuer Wert bzw. Inhalt des geänderten Dict-Objektes
  • "==": unveränderte Dict-Objekte

Um die Unterschiede in den Ebenen

  • Systemindex: geänderte Objekttypen,
  • Objekttypindex: geänderte Funktionen,
  • Funktionsindex: geänderte Parameter für URI-Parameter-Zeichenkette,
  • Systemdatenverzeichnis: geänderte Parameter für "write"-Funktionen bzw. Request Body

auszugeben, stehen für die jeweiligen Abfragen folgende (nicht in den Indexebenen dokumentierte) Parameter zur Verfügung:

diff_version=<diff_vmajor>.<diff_vminor>
strict_mode=[true | false]
  • diff_version gibt die Ziel-Versionsnummer an, zu der ein Vergleich erfolgen soll. Quell-Versionsnummer ist hierbei immer die im URI verwendete.
  • strict_mode gibt an, ob eine vollständige (strikte) Ausgabe der Unterschiede erfolgen soll oder ob die Ausgabe vereinfacht sein soll.
    • true (Standardwert): es werden alle Dict-Objekte der o.g. Änderungskategorien ausgegeben
    • false: es werden nur nicht-leere und keine unveränderten Dict-Objekte ausgegeben

Beispiele

Abfragen von Systemdaten

Die Abfrage des Systemdatenverzeichnisses (Data Dictionary, unter wapi/datadict) erlaubt es, vorhandene Zuordnungen von Parametern zu Datenmanipulations-Funktionen festzustellen sowie die optionalen Key-Value-Zuordnungen abzufragen. Die Ausgabe erfolgt indexweise strukturiert nach:

  • System (äußeres Dict-Objekt, Bezeichner ist der Systemname selbst),
  • Objekttyp (Bezeichner "ObjectTypeDict"),
  • Funktion (Bezeichner "FunctionDict"),
  • Parameter (Bezeichner "ParameterDict"),
  • Key-Value-Attribute (Bezeichner "KeyValDict"). Diese können von der Zuordnung zu anderen Objekttypen abhängig sein; in diesem Fall wird der betreffende Objekttyp unter "KeyValDepdntObjectTypeDict" angegeben. Die Ausgabe der nur für diesen Objekttyp gültigen Key-Value-Attribute erfolgt separat über die Abfrage von Anwendungsdaten unter Angabe der Objekttyp-Daten (Parameter / im URI-Schema).

In der Parameterliste werden zusätzliche Attribute (z.B. Alt/Neubelegung und deren Standardwerte, Nullbarkeit, Datentyp, Datenrückgabe) ausgegeben. Damit sind die für die Aufstellung von Transaktionsplänen erforderlichen Informationen zur System-, Objekttyp-, Funktions- und Parameterbelegung automatisch dokumentiert und verfügbar.

Beispiel

Abfragen von Anwendungsdaten

Darunter sollen alle übrigen Abfragen zu anwendungsbezogenen Benutzerdaten (Objekte incl. Transaktionspläne und deren Attribute) verstanden werden.

Beispiel

Datenstrukturabfragen

Um die Datenstruktur einer Request-Antwort zu erfassen, können die Funktionen des Modus "inspect" verwendet werden. Die Inspect-Funktion ruft dabei standardmäßig die Funktion list des selben Objekttyps auf und gibt eine leere Struktur (Skelett) ihrer Ausgabedaten zurück. Eine anderslautende Funktion kann mit dem Parameter "function_name" angegeben werden. Umgekehrt muß die aufgerufene Funktion “inspizierbar” sein, sie muß also den Modus "inspectable" haben. Um Unterschiede der Ausgabedatenstruktur einer inspizierbaren Funktion zwischen zwei verschiedenen Versionen zu erkennen, können (analog zu den Indexabfragen) die Parameter

diff_version=<diff_vmajor>.<diff_vminor>
strict_mode=[true | false]

verwendet werden. Die Inspect-Funktion selbst hat keine eigene Datenstruktur, denn sie gibt immer die Struktur der angegebenen inspizierbaren Funktion bzw. den Strukturvergleich zweier Versionen der angegebenen inspizierbaren Funktion zurück.

Beispiele

Requests zur Dateneingabe (Datenmanipulation)

Generelles

Sämtliche Requests für Datenmanipulationen basieren auf der Übertragung des Request Body, der die detaillierten Informationen zur jeweiligen Funktion enthält. Die Antwort ist im Normalfall ein JSON-Array (leer bzw. -falls für die Funktion vorgesehen- mit den entsprechenden Antwortparametern als JSON-Dict-Objekte); im Fehlerfall besteht sie aus den Fehlerparametern als JSON-Dict-Objekt. Datenmanipulationsfunktionen sind in der Funktionsindex-Abfrage durch den Modus "write" erkennbar.

Kernbestandteile eines Requests sind:

  • WebAPI-System-Name
  • WebAPI-Objekttyp-Name
  • WebAPI-Funktion
  • Parameterliste mit allen Angaben der zu manipulierenden Daten: Die Parameternamen sowie deren Datentypen können über die Abfrage von Systemdaten ermittelt werden.
  • Optionale Key-Value-Attribute: Je nach WebAPI-Objekttyp erforderlich und ebenfalls über die Abfrage von Systemdaten ermittelbar. Es kann darüberhinaus eine zusätzliche Abhängigkeit von weiteren Objekttypen bestehen; die für den konkreten Fall geltenden Key-Value-Attribute können über die Abfrage von Anwendungsdaten ermittelt werden.

Eine Ausnahme hiervon bildet die Ausführung von Transaktionsplänen, da die erforderlichen Kernbestandteile bereits im Transaktionsplan gespeichert sind. Hierzu ist lediglich die eindeutige Angabe des auszuführenden Transaktionsplans in der URI-Parameterzeichenkette erforderlich. Diese Requests funktionieren ohne Übertragung eines Request Body.

Zusammenwirken von URI-Parametern und Request Body

Für den Aufbau gelten die nachfolgenden Formen und Muster. Werte in spitzen Klammern <> sind Platzhalter, wobei Textdaten bzw. -werte innerhalb von Anführungsstrichen "" stehen müssen; numerische Daten bzw. Werte stehen dagegen ohne Anführungsstriche. Drei aufeinanderfolgende Punkte ... stehen für Wiederholungen im Listenkontext (Dict-Objekte/Arrays).

Erste Form: Einfache Dateneingabe durch einen URI-basierten Request

Mit dieser Methode lassen sich (z.B. einfache, voneinander unabhängige) Datenmanipulationen, die

  • nicht systemübergreifend sind (sich also nur auf Objekttypen ein und desselben Systems beziehen) und
  • nicht objekttypübergreifend sind (sich also nur auf Objekte ein und desselben Typs beziehen) und
  • ein und dieselbe Funktion beinhalten,

transaktional, d.h. innerhalb eines WebAPI-Requests, ausführen. Die Parameter “Systemname”, “Objekttyp-Name” und “Funktion” sind in der URI-Adresse vorgegeben und daher für alle im Request enthaltenen Datenmanipulationen konstant. Diese Methode ist deshalb auch für die Anwendung in REST-basierten Umgebungen (Representational State Transfer) geeignet. Die zu manipulierenden Daten (Array von Dict-Objekten) werden über den HTTP Request Body eingegeben. Ein solches Dict-Objekt entspricht einem Datenmanipulations-Befehl bzw. -Statement und hat nachfolgende Struktur. Für die Elemente der in einem Dict-Objekt (Statement) enthaltenen Parameter-Liste gibt es 2 alternative Varianten, von denen elementeweise genau eine erlaubt ist:

  • Variante 1 ermöglicht die statische (direkte) Angabe der Parameterwerte;
  • Variante 2 ermöglicht es, die Parameterwerte dynamisch unter Bezugnahme auf Rückgabewerte von Parametern in vorhergehenden Statements zur Laufzeit zu bestimmen. Dabei muß der Bezugsparameter als Rückgabeparameter definiert sein.

Diese Definitionen lassen sich über das Systemdatenverzeichnis abfragen.

Aufbau eines Dict-Objekts (Statement):

  • Parameter-Liste mit Elementen der Variante 1 oder 2 (nachfolgend beschrieben)

  • optionale Key-Value-Liste mit folgenden Elementen:

    • Schlüsselwort (Key)
    • Wert (Value)

Aufbau der Elemente der Parameter-Liste:

  • Variante 1: statische Angabe

    • Parametername (Schlüssel)
    • alter Wert
    • neuer Wert
  • Variante 2: dynamische Angabe, d.h. die Parameterwerte werden aus den Rückgabewerten eines vorhergehenden Statements bezogen.

    • Parametername (Schlüssel)
    • für alten Wert: Pos. eines vorhergehenden Statements, das den Bezugsparameter enthält
    • für alten Wert: Name des dort enthaltenen Bezugsparameters
    • für alten Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters
    • für neuen Wert: Pos. eines vorhergehenden Statements, das den Bezugsparameter enthält
    • für neuen Wert: Name des dort enthaltenen Bezugsparameters
    • für neuen Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters

Muster

  • URI:
<BASE-URI>/<ROOT>/<vmajor>.<vminor>/<sys>/<objtype>/<function>
  • Request Body, Variante 1:
[
  {
    "param_list":
      [
        { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },
  ...
]
  • Request Body, Variante 1 mit 2 kombiniert, Position des Bezugsparameter-Statements = 1 bzw. 2:
[

  {
    "param_list":
      [
        { "name": <param_name1>, "old_value": <old_param_value1>, "new_value": <new_param_value1> },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },

  {
    "param_list":
      [
        { "name": <param_name3>, "old_value": <old_param_value2>, "new_value": <new_param_value2> },
        { "name": <param_name4>,
          "old_ret_stmt_pos": 1, "old_ret_stmt_param": <param_name1>, "old_ret_stmt_state": "old" | "new",
          "new_ret_stmt_pos": 2, "new_ret_stmt_param": <param_name2>, "new_ret_stmt_state": "old" | "new"
        },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },

  ...
]
  • Antwort, falls keine Rückgabeparameter verwendet wurden:
[]

[-> Beispiel mit leerer Antwort]

  • Antwort, falls Rückgabeparameter verwendet wurden:
[
    {
        "function_name": <func_name>,
        "objecttype_name": <ot_name>,
        "param_list": [
            {
                "name": <param_name>,
                "new_value": <new_param_value>,
                "old_value": <old_param_value>
            }
        ],
        "statement_pos": <pos>,
        "system_name": <sys_name>
    }
]

[-> Beispiel mit nicht-leerer Antwort]

Zweite Form: Komplexe Dateneingabe über einen temporären Transaktionsplan

Mit dieser Methode lassen sich (z.B. einmalige) Datenmanipulationen, die

  • systemübergreifend sind oder
  • objekttypübergreifend sind oder
  • verschiedene Funktionen beinhalten,

transaktional ausführen, indem diese als temporärer Transaktionsplan direkt zur Ausführung gebracht werden. Dieser wird durch den Request Body übergegeben und besteht aus einer Liste von Dict-Objekten. Ein solches Dict-Objekt entspricht einem Datenmanipulations-Befehl bzw. -Statement und hat die nachfolgende Struktur. Für die Elemente der in einem Dict-Objekt (Statement) enthaltenen Parameter-Liste gibt es 2 alternative Varianten, von denen elementeweise genau eine erlaubt ist:

  • Variante 1 ermöglicht die statische (direkte) Angabe der Parameterwerte;
  • Variante 2 ermöglicht es, die Parameterwerte dynamisch unter Bezugnahme auf Rückgabewerte von Parametern in vorhergehenden Statements zur Laufzeit zu bestimmen. Dabei muß der Bezugsparameter als Rückgabeparameter definiert sein.

Diese Definitionen lassen sich über das Systemdatenverzeichnis abfragen.

Aufbau eines Dict-Objekts (Statement):

  • System-Name
  • Objekttyp-Name
  • Funktions-Name
  • Parameter-Liste mit Elementen der Variante 1 oder 2 (nachfolgend beschrieben)
  • optionale Key-Value-Liste mit folgenden Elementen:
    • Schlüsselwort (Key)
    • Wert (Value)

Aufbau der Elemente der Parameter-Liste:

  • Variante 1: statische Angabe

    • Parametername (Schlüssel)
    • alter Wert
    • neuer Wert
  • Variante 2: dynamische Angabe

    • Parametername (Schlüssel)
    • für alten Wert: Pos. eines vorhergehenden Statements, das den Bezugsparameter enthält
    • für alten Wert: Name des dort enthaltenen Bezugsparameters
    • für alten Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters
    • für neuen Wert: Pos. eines vorhergehenden Statements
    • für neuen Wert: Name des dort enthaltenen Bezugsparameters
    • für neuen Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters

Die Erstellung des temporären Transaktionsplans und die Ausführung der eigentlichen, darin geplanten Datenmanipulationen sowie die abschließende Löschung des temporären Transaktionsplans erfolgen in einem Schritt durch das Ausführen des Transaktionsplans (Funktion "run_immediate"). Diese drei Schritte sind nicht entkoppelbar und erfolgen intern innerhalb ein und derselben Datenbank-Transaktion.

Muster

  • URI:
<BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/transaction/run_immediate
  • Request Body:
[
  {
    "system_name": <sys_name>,
    "objecttype_name": <ot_name>,
    "function_name": <func_name>,
    "param_list":
      [
        { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },
  ...
]
  • Antwort, falls keine Rückgabeparameter verwendet wurden:
[]

[-> Beispiel]

Dritte Form: Komplexe Dateneingabe über nicht-temporäre Transaktionspläne

Mit dieser Methode lassen sich (z.B. alternierende oder sich zyklisch wiederholende) Datenmanipulationen, die

  • systemübergreifend sind oder
  • objekttypübergreifend sind oder
  • verschiedene Funktionen beinhalten,

transaktional ausführen, indem diese mittels vorbereitendem (ersten) Schritt in einem Transaktionsplan (oder mehreren TA-Plänen) zusammengestellt werden. Für diesen Vorbereitungsschritt der Erstellung von TA-Plänen ist genau ein Request erforderlich. Die TA-Plan-Daten werden über den HTTP Request Body als Liste von Dict-Objekten eingegeben. Jedes dieser Dict-Objekte repräsentiert demnach einen separaten TA-Plan und hat die nachfolgende Struktur. Für die Elemente der in einem Statement enthaltenen Parameter-Liste gibt es 2 alternative Varianten, von denen elementeweise genau eine erlaubt ist:

  • Variante 1 ermöglicht die statische (direkte) Angabe der Parameterwerte;
  • Variante 2 ermöglicht es, die Parameterwerte dynamisch unter Bezugnahme auf Rückgabewerte von Parametern in vorhergehenden Statements zur Laufzeit zu bestimmen. Dabei muß der Bezugsparameter als Rückgabeparameter definiert sein.

Diese Definitionen lassen sich über das Systemdatenverzeichnis abfragen.

Aufbau eines TA-Plans:

  • Kopfdaten des TA-Plans:
    • Name
    • Ausführungszeit
    • Liste der Benutzer-Accounts, die diesen TA-Plan unter der User-ID des Eigentümers (und folglich mit dessen Rechten) ausführen dürfen
    • Liste der Datenmanipulations-Befehle bzw. -Statements. Pro Befehl gibt es folgende Parameter:
      • System-Name
      • Objekttyp-Name
      • Funktions-Name
      • Parameter-Liste mit Elementen der Variante 1 oder 2 (nachfolgend beschrieben)
      • optionale Key-Value-Liste mit folgenden Elementen:
        • Schlüsselwort (Key)
        • Wert (Value)

Aufbau der Elemente der Parameter-Liste:

  • Variante 1: statische Angabe

    • Parametername (Schlüssel)
    • alter Wert
    • neuer Wert
  • Variante 2: dynamische Angabe

    • Parametername (Schlüssel)
    • für alten Wert: Pos. eines vorhergehenden Statements, das den Bezugsparameter enthält
    • für alten Wert: Name des dort enthaltenen Bezugsparameters
    • für alten Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters
    • für neuen Wert: Pos. eines vorhergehenden Statements
    • für neuen Wert: Name des dort enthaltenen Bezugsparameters
    • für neuen Wert: Status (alt/neu) des dort enthaltenen Bezugsparameters

Änderungen und Löschungen von Transaktionsplänen erfolgen auf analoge Weise. Neben create und delete stehen für Änderungen die Funktionen

  • update: nur für das Ändern der Kopfdaten
  • append: für das Ergänzen von Transaktionsbefehlen (auch listenweise; kann mit truncate kombiniert werden)
  • truncate: für das Leeren von Transaktionsplänen (es werden nur die Transaktionsbefehle gelöscht, aber die Kopfdaten bleiben erhalten)

zur Verfügung. Ein Transaktionsplan kann nicht durch einen anderen Transaktionsplan erstellt werden; hierfür ist ausschließlich der URI-basierte Request möglich.

Die Umsetzung der eigentlichen, darin geplanten Datenmanipulationen erfolgt erst durch die Ausführung eines TA-Plans (Funktion run) als zweiter (oder weiterer) Schritt und ist daher völlig entkoppelt vom obigen ersten Schritt. Aufrufparameter ist standardmäßig nur “name” zur Angabe des Namens des Transaktionsplans. Soll ein Transaktionsplan ausgeführt werden, der einem fremden Eigentümer gehört (also nicht dem, der ihn aufruft), muß zusätzlich noch der Eigentümer-Account (Login-Name) durch den Parameter "owner_user" angegeben werden. Pro Request kann genau ein TA-Plan ausgeführt werden.

Muster

  • URI zum Erzeugen eines (bzw. mehrerer) nicht-temporären Transaktionsplans (bzw. -pläne):
<BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/transaction/create
  • Request Body:
[
  {
    "name": <transaction_name>,
    "exec_timestamp": <dd.mm.yyyy HH:MM:SS>,
    "exec_user_list": [<login_name>, ...],
    "statement_list":
      [
        {
          "system_name": <sys_name>,
          "objecttype_name": <ot_name>,
          "function_name": <func_name>,
          "param_list":
            [
              { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
              ...
            ],
          "keyval_dict":
            {
              "<key_word>": <value>,
              ...
            }
        },
        ...
      ]
  },
  ...
]
  • Antwort, falls keine Rückgabeparameter verwendet wurden:
[]
  • URI zum Ausführen eines bereits gespeicherten, nicht-temporären Transaktionsplans:
<BASE-URI>/<ROOT>/<vmajor>.<vminor>/wapi/transaction/run?name=<transaction_name>
  • Request Body: leer
  • Antwort, falls keine Rückgabeparameter verwendet wurden:
[]

[-> 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, welche zusätzlich für die Ausführung von Transaktionsplänen (Datenmanipulation) vorgesehen ist. Sie bezieht sich auf die Version der internen Schnittstelle zwischen WebAPI und der darunterliegenden Datenbank (NetDB). Die Versionsangabe bei Datenausgabe-Aufrufen kann dagegen nur über die numerische Angabe geschehen. Beispiele für den Status einer Version (semantische Versionsangaben):

  • alpha: Entwicklung
  • beta: Testbetrieb für begrenzten Anwenderkreis freigegeben
  • rc: Veröffentlichungskandidat (release candidate), abschließende Testversion
  • release: aktuelle Version
  • oldrelease: veraltete Version (Vorgänger der aktuellen Version)
  • deprecated: nicht mehr unterstützte Version (Vorgänger der veralteten Version)

Pro System ist jede semantische Version bzw. jeder Versionsstatus genau einer numerischen Version zugeordnet, wobei letztere je System verschieden sein kann (s. Versionsindex). D.h., jedes System kann z.B. im Status release unter einer anderen numerischen Version laufen. Die nahtlose Umschaltung auf eine höhere Version (Versionswechsel durch Änderung dieser Zuordnung) kann somit pro System separat vorgenommen werden. WebAPI-Funktionsaufrufe mit numerischer Versionsangabe umgehen grundsätzlich diese Zuordnung. Clients, die die numerische Versionsangabe benutzen, sind folglich von dieser Änderung unabhängig (nicht betroffen). Clients, die in Transaktionsplan-Aufrufen die semantische Versionsangabe benutzen, werden automatisch auf die aktuell dem jeweiligen System zugeordnete numerische Version geleitet.

Entwicklungs- bzw. Testversionen können sich jederzeit unangekündigt ändern (sowohl in der Versionsnummer als auch im Status als auch im Verhalten des Codes) und dürfen daher nur unter Vorbehalt benutzt werden.

Altversionen (Status oldrelease) des API werden bis zum nächsten Versionswechsel bereitgehalten; danach werden sie letztmalig im Status deprecated bis zum darauf folgenden Versionswechsel bereitgehalten. Die Frist für einen bevorstehenden Versionswechsel wird angekündigt und beträgt normalerweise 3 Monate. Demnach liegt die Frist für die endgültige Abschaltung einer Version normalerweise bei 6 Monaten. Wir empfehlen aber, Clients bereits auf die aktuelle Version anzupassen, solange sie noch unter der Altversion laufen.

Beispiel-Szenarium für einen Versionswechsel im System dns

  • vorher:
    • semantische Version beta ist numerischer Version 1.1 zugeordnet
    • semantische Version release ist numerischer Version 1.0 zugeordnet
    • semantische Version oldrelease ist numerischer Version 0.9 zugeordnet
    • semantische Version deprecated ist numerischer Version 0.8 zugeordnet
  • nachher (Freigabe der beta-Version als neue release-Version)
    • [NEU] semantische Version beta ist numerischer Version 1.2 zugeordnet
    • semantische Version release ist numerischer Version 1.1 zugeordnet
    • semantische Version oldrelease ist numerischer Version 1.0 zugeordnet
    • semantische Version deprecated ist numerischer Version 0.9 zugeordnet
    • [ALT] numerische Version 0.8 ist abgeschaltet und nicht mehr verfügbar

Wird z.B. ein Transaktionsplan mit der Version release für das System dns aufgerufen, so würde vor dem Versionswechsel die numerische Version 1.0 zugeordnet. Nach dem Versionswechsel würde die numerische Version 1.1 zugeordnet.

Da die semantische Versionsangabe systemweise verschieden sein kann, kann diese nur bei Ausführen von Transaktionsplänen verwendet werden. Die Versionsangabe in der URI-Adresse gilt immer für die komplette Transaktion und ist nur bei Ausführen von Transaktionsplänen (systemweise oder komplett) davon abweichend definierbar.

Numerische Versionsangabe

Angabe durch URI

  • entspricht dem Standard-URI-Schema

[-> Beispiel]

Angabe bei Transaktionsplan-Aufrufen

  • mit Hilfe der systembezogenen Versionsparameter in der Parameterzeichenkette:
v_<system_name>=<vmajor>.<vminor>
  • mit Hilfe des globalen Versionsparameters in der Parameterzeichenkette:
v=<vmajor>.<vminor>

[-> Beispiel]

Semantische Versionsangabe

Angabe durch URI

  • nicht möglich: da die Versionsangabe in der URI-Adresse als Standardwert für alle Systeme innerhalb des Transaktionsplans gilt, kann die semantische Versionsangabe nur systembezogen bei Transaktionsplan-Aufrufen verwendet werden.

Angabe bei Transaktionsplan-Aufrufen

  • mit Hilfe der systembezogenen Versionsparameter in der Parameterzeichenkette, wobei jeder Parameter genau einmal vorkommen darf:
v_<system_name>=<version_name>
  • mit Hilfe des globalen Versionsparameters v in der Parameterzeichenkette, wobei dieser genau einmal vorkommen darf und keine systembezogenen Versionsparameter vorkommen dürfen:
v=<version_name>

[-> Beispiel]

Versionsangabe durch Versionsparameter in der Parameterzeichenkette

Alle Versionsparameter haben grundsätzlich Vorrang vor der im URI angegebenen Version, wobei diese als Eintrittspunkt für den Basisaufruf der Transaktion erforderlich ist. Die systembezogenen Versionsparameter können sowohl in der numerischen als auch in der semantischen Form gleichzeitig verwendet werden (pro System darf aber nur genau eine Versionsdefinition gemacht werden). Für Transaktionsbefehle in Systemen, deren Version durch keinen Versionsparameter explizit definiert ist, gilt die im URI angegebene Version.

[-> Beispiel]

Versionsänderungen

siehe Indexabfragen zum Versionsvergleich