Kompaktübersicht

Basisadresse

https://www-net.scc.kit.edu       "Produktionsumgebung"
https://www-net-test.scc.kit.edu  "Testumgebung"
https://www-net-devel.scc.kit.edu "Entwicklungsumgebung"

[-> Haupt-Dokumentation]

Ebenen im URI-Schema unterhalb der Basisadresse

Das URI-Schema ist hierarchisch (Baumstruktur), 4stufig, und jede Ebene ist über Pfadangaben erreichbar. Jede Ebene außer der untersten (4.) liefert durch Indexabfragen Informationen über die Elemente der nächsten darunterliegenden Ebene. Indexabfragen sind durch einen abschließenden Schrägstrich / (Slash) im URI gekennzeichnet. Die oberste Ebene /api/ (Stamm- oder Wurzelebene) ist konstant; alle darunterliegenden Ebenen sind potentiell als veränderbar zu betrachten.

  • oberste Ebene /api/:
    • Inhalt: numerische Versionen <majorversion>.<minorversion>, die in der WebAPI ansprechbar bzw. adressierbar sind, um einen nahtlosen Übergang bei Versionswechseln zu erreichen
    • Index:
      • "VersionNameIndex" zeigt die systemweise Zuordnung von semantischer zu numerischer Version
      • "VersionNumIndex" zeigt die systemweise Zuordnung von numerischer zu semantischer Version
    • semantische Versionsangaben können in Transaktionsplänen benutzt werden
  • Versionsebene /api/<majorversion>.<minorversion>/:
    • Inhalt: Systeme. Dies sind
      • thematische Bereiche für anwendungs- oder nutzerspezifische Daten wie z.B. dns, nd, dhcp oder
      • der interne Bereich der WebAPI selbst (wapi) für zentrale Funktionen wie Transaktionspläne, Systemdatenverzeichnis.
    • Index: "SystemIndex" zeigt die verfügbaren Systeme mit Name und Kurzbeschreibung
  • Systemebene /api/<majorversion>.<minorversion>/<systemname>/:
    • Inhalt: Objekttypen, also Datenarten, nach denen alle Objekte systemweise kategorisiert werden, wie z.B. dns/fqdn, nd/modul, dhcp/lease
    • Index: "ObjectTypeIndex" zeigt die im adressierten System verfügbaren Objekttypen mit Name und Kurzbeschreibung
  • Objekttypebene /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/:
    • Inhalt: Funktionen, also Methoden, mit denen Daten eines oder mehrerer Objekte des adressierten Objekttyps und Systems
      • eingegeben/geändert/gelöscht werden können (z.B. nd/modul/update, dhcp/lease/delete) oder
      • ausgegeben werden können (z.B. dns/fqdn/list)
    • Index: "FunctionIndex" zeigt die für das adressierten System und den adressierten Objekttyp verfübaren Funktionen mit
      • Name, Modus und Parametern bei Ausgabefunktionen
      • Name, Modus bei Eingabefunktionen (Parameter nur über Systemdatenverzeichnis)

[-> Haupt-Dokumentation]

Datenausgabe

  • Systemnamen, Objekttypnamen aus Indexabfragen ("SystemIndex", "ObjectTypeIndex") bestimmen, falls nicht schon bekannt
  • Funktionsnamen und verfügbare Parameter aus "FunctionIndex" bestimmen, falls nicht schon bekannt:
    • Funktionsname ist typischerweise list
    • generische Abfrage über Funktionsindex: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/, "mode" muß "read" enthalten
    • verfügbare Funktionsparameter jeweils unter Bezeichner "params_dict"
  • Parameter und deren Werte können wahlweise in der URI-Parameterzeichenkette (GET-Request) oder im Request Body (POST-Request) übergeben werden
  • Datenstruktur des Abfrageergebnisses kann über <systemname>/<objekttypname>/list_datastructure angezeigt werden
  • Aufruf-URI unterhalb der Basisadresse: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/<funktionsname>?<parameter_mit_werten>

[-> Haupt-Dokumentation]

Dateneingabe (einfach)

  • Systemnamen, Objekttypnamen aus "SystemIndex", "ObjectTypeIndex" bestimmen, falls nicht schon bekannt
  • Funktionsnamen und verfügbare Parameter aus "FunctionIndex" bestimmen, falls nicht schon bekannt:
    • generische Abfrage über Funktionsindex: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/, "mode" muß "write" enthalten
    • verfügbare Funktionsparameter zu gegebenem <systemname>, <objekttypname> und <funktionsname> aus Systemdatenverzeichnis bestimmen: /api/<majorversion>.<minorversion>/wapi/datadict/list?sys_name=<systemname>&ot_name=<objekttypname>&function_name=<funktionsname>
  • Parameter und deren Werte müssen als JSON-Array im Request Body (POST-Request) übergeben werden. Schema:
[
  {
    "param_list":
      [
        { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },
  ...
]
  • Datenstruktur des Ergebnisses kann über wapi/transaction/list_datastructure?function_name=run angezeigt werden
  • Aufruf-URI unterhalb der Basisadresse: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/<funktionsname>

[-> Haupt-Dokumentation]

Dateneingabe (komplex, temporärer TA-Plan)

  • Systemnamen, Objekttypnamen aus "SystemIndex", "ObjectTypeIndex" bestimmen, falls nicht schon bekannt
  • Funktionsnamen und verfügbare Parameter aus "FunctionIndex" bestimmen, falls nicht schon bekannt:
    • generische Abfrage über Funktionsindex: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/, "mode" muß "write" enthalten
    • verfügbare Funktionsparameter zu gegebenem <systemname>, <objekttypname> und <funktionsname> aus Systemdatenverzeichnis bestimmen: /api/<majorversion>.<minorversion>/wapi/datadict/list?sys_name=<systemname>&ot_name=<objekttypname>&function_name=<funktionsname>
  • <systemname>, <objekttypname>, <funktionsname> sowie alle Parameter und deren Werte müssen als JSON-Array im Request Body (POST-Request) übergeben werden. Schema:
[
  {
    "system_name": <systemname>,
    "objecttype_name": <objekttypname>,
    "function_name": <funktionsname>,
    "param_list":
      [
        { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
        ...
      ],
    "keyval_dict":
      {
        "<key_word>": <value>,
        ...
      }
  },
  ...
]
  • Datenstruktur des Ergebnisses kann über wapi/transaction/list_datastructure?function_name=run angezeigt werden
  • Aufruf-URI unterhalb der Basisadresse: /api/<majorversion>.<minorversion>/wapi/transaction/run_immediate

[-> Haupt-Dokumentation]

Dateneingabe (komplex, nicht-temporärer TA-Plan)

  • TA-Kopfdaten festlegen:
    • Name <transactionsname>
    • Ausführungszeit <dd.mm.yyyy HH:MM:SS>
    • Liste der Benutzer-Accounts (<login_name>), die diesen TA-Plan mit Eigentümer-Rechten ausführen dürfen
  • Befehlsliste festlegen. Für jeden Befehl werden benötigt:
    • Systemnamen, Objekttypnamen aus "SystemIndex", "ObjectTypeIndex" bestimmen, falls nicht schon bekannt
    • Funktionsnamen und verfügbare Parameter aus "FunctionIndex" bestimmen, falls nicht schon bekannt:
      • generische Abfrage über Funktionsindex: /api/<majorversion>.<minorversion>/<systemname>/<objekttypname>/, "mode" muß "write" enthalten
      • verfügbare Funktionsparameter zu gegebenem <systemname>, <objekttypname> und <funktionsname> aus Systemdatenverzeichnis bestimmen: /api/<majorversion>.<minorversion>/wapi/datadict/list?sys_name=<systemname>&ot_name=<objekttypname>&function_name=<funktionsname>
  • TA-Plan anlegen. Alle TA-Daten müssen als JSON-Array im Request Body (POST-Request) übergeben werden. Schema:
[
  {
    "name": <transactionsname>,
    "exec_timestamp": <dd.mm.yyyy HH:MM:SS>,
    "exec_user_list": [<login_name>, ...],
    "statement_list":
      [
        {
          "system_name": <systemname>,
          "objecttype_name": <objekttypname>,
          "function_name": <funktionsname>,
          "param_list":
            [
              { "name": <param_name>, "old_value": <old_param_value>, "new_value": <new_param_value> },
              ...
            ],
          "keyval_dict":
            {
              "<key_word>": <value>,
              ...
            }
        },
        ...
      ]
  },
  ...
]
  • Datenstruktur des Ergebnisses (für create oder run) kann über wapi/transaction/list_datastructure?function_name=run angezeigt werden
  • Aufruf-URIs unterhalb der Basisadresse:
    • TA-Plan anlegen (TA-Daten via Request Body): /api/<majorversion>.<minorversion>/wapi/transaction/create
    • eigenen TA-Plan ausführen, ohne Request Body: /api/<majorversion>.<minorversion>/wapi/transaction/run?name=<transactionsname>
    • nicht-eigenen TA-Plan (Eigentümer ist <login_name>) ausführen, ohne Request Body: /api/<majorversion>.<minorversion>/wapi/transaction/run?name=<transactionsname>&owner_user=<login_name>

[-> Haupt-Dokumentation]

Versionswechsel

  • Um Codeanpassungen bei einem Versionswechsel vorzunehmen, können die Versionsunterschiede bei Indexabfragen und im Systemdatenverzeichnis gezielt abgefragt werden (erst ab Version 2.0). Der Ausgabemodus kann mit dem Parameter strict_mode gesteuert werden:
    • true (Standardwert): Vollmodus, es werden alle Dict-Objekte ausgegeben
    • false: Einfacher Modus, es werden nur nicht-leere und keine unveränderten Dict-Objekte ausgegeben
  • Versionsunterschiede bei Indexabfragen müssen ebenenweise festgestellt werden.
  • Versionsunterschiede im Systemdatenverzeichnis können wahlweise global oder systembezogen/objekttypbezogen/funktionsbezogen festgestellt werden.
  • Versionsunterschiede von 2.0 zu 2.1 aus Systemdatenverzeichnis bestimmen:
    • Unterschiede global (einfacher Modus) ausgeben: /api/2.0/wapi/datadict/list?diff_version=2.1&strict_mode=false
    • Unterschiede nur für <systemname>, <objekttypname> und <funktionsname> ausgeben (ausführliche Form): /api/2.0/wapi/datadict/list?diff_version=2.1&sys_name=<systemname>&ot_name=<objekttypname>&function_name=<funktionsname>
  • Versionsunterschiede von 2.0 zu 2.1 in einfachem Modus auf Funktionsebene für dns/record/list ausgeben: /api/2.0/dns/record/list_datastructure?diff_version=2.1&strict_mode=false&function_name=list
  • Hinweis: Weil die Vergleichsfunktion rein Dict-Objekt-basiert ist, müssen die numerisch indizierten Elemente von JSON-Arrays in Dict-Bezeichner umgesetzt werden. Das Datenstruktur-Skelett besteht typischerweise aus einem JSON-Array mit genau einem Dict-Objekt. Dieses wird (da null-basiert) als "0" indiziert.

[-> Haupt-Dokumentation]