Kompaktübersicht

Basisadresse

https://api.netdb.scc.kit.edu       "Produktionsumgebung"
https://api.netdb-test.scc.kit.edu  "Testumgebung"
https://api.netdb-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 und parameterlos. 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> mit Zuordnung zu semantischen Versionen, die in der WebAPI ansprechbar bzw. adressierbar sind, um einen nahtlosen Übergang bei Versionswechseln zu erreichen.
  • Versionsebene /api/<majorversion>.<minorversion>/:
    • Inhalt: Systeme mit Name und Kurzbeschreibung, die in der adressierten Version verfügbar sind. 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 Transaktionsaufrufe, Systemdatenverzeichnis.
    • Die Abfrage ist identisch zu
/api/<majorversion>.<minorversion>/wapi/system/list
  • Systemebene /api/<majorversion>.<minorversion>/<system_name>/:
    • Inhalt: Objekttypen des adressierten Systems, wie z.B. dns/fqdn, nd/module, dhcp/lease.
    • Die Abfrage ist identisch zu
/api/<majorversion>.<minorversion>/wapi/object_type/list?system_list=["<system_name>"]
  • Objekttypebene /api/<majorversion>.<minorversion>/<system_name>/<object_type_name>/:
    • Inhalt: Funktionen des adressierten Objekttyps, also Methoden, mit denen Daten eines oder mehrerer Objekte des adressierten Objekttyps und Systems
      • modifiziert werden können (z.B. nd/module/update, dhcp/lease/delete) oder
      • ausgegeben werden können (z.B. dns/fqdn/list)
    • Die Abfrage ist identisch zu
/api/<majorversion>.<minorversion>/wapi/function/list?system_list=["<system_name>"]&object_type_list=["<object_type_name>"]

[-> Haupt-Dokumentation]

Erforderliche Daten für Transaktion vorbereiten

  • Systemnamen, Objekttypnamen, Constraintnamen aus Systemindex und Objekttypindex bestimmen, falls nicht schon bekannt
    • generische Abfrage über Objekttypindex /api/<majorversion>.<minorversion>/<system_name>/
    • oder verfügbare Objekttypen zu gegebenem <system_name> aus Systemdatenverzeichnis bestimmen:
/api/<majorversion>.<minorversion>/wapi/object_type/list?system_list=["<system_name>"]
  • Funktionsnamen und verfügbare Parameter aus Funktionsindex bestimmen, falls nicht schon bekannt:
    • generische Abfrage über Funktionsindex: /api/<majorversion>.<minorversion>/<system_name>/<object_type_name>/
    • oder verfügbare Funktionsparameter zu gegebenem <system_name>, <object_type_name> und <function_name> aus Systemdatenverzeichnis bestimmen:
/api/<majorversion>.<minorversion>/wapi/function/list?system_list=["<system_name>"]&object_type_list=["<object_type_name>"]

GET-Request (Einzelbefehls-Transaktion, nur für nicht-datenmodifizierende Funktionen)

  • Parameternamen im <query_string> entsprechen denen der Altbelegung aus Funktionsindex bzw. Systemdatenabfrage
  • Aufruf-URI unterhalb der Basisadresse:
/api/<majorversion>.<minorversion>/<system_name>/<object_type_name>/<function_name>?<query_string>

[-> Haupt-Dokumentation]

POST-Request (Einzelbefehls-Transaktion)

  • <system_name>, <object_type_name>, <function_name> werden im Aufruf-URI angegeben.
  • Parameternamen und deren Werte müssen im Request Body übergeben werden. Schema:
{
  "old": { "<param_name>": "param_value" },
  "new": { "<param_name>": "param_value" }
}
  • Aufruf-URI unterhalb der Basisadresse:
/api/<majorversion>.<minorversion>/<system_name>/<object_type_name>/<function_name>

[-> Haupt-Dokumentation]

POST-Request (generische Transaktion)

  • "<stmt_idx>", <system_name>, <object_type_name>, <function_name>, Constraints sowie alle Parameter und deren Werte müssen pro Statement separat übergeben werden. "idx" ist optional und "<stmt_idx>" ist transaktionsweit eindeutig und nicht nullbar. Wenn "idx" nicht angegeben wurde, wird die Statement-Position automatisch intern eingesetzt. "<ref_stmt_idx>" und "<join_stmt_idx>" müssen sich auf den Index eines vorausgehenden Statements beziehen. Schema:
[
  {
    "idx": "<stmt_idx>",
    "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>" | "default" | null}
  }
]
  • Aufruf-URI unterhalb der Basisadresse:
/api/<majorversion>.<minorversion>/wapi/transaction/execute
  • oder explizit den Test-Modus durch den Parameter dry_mode=true angeben: Es werden keine Daten permanent gespeichert; alle Ausgabedaten sind aber gegenüber dem Normal-Modus dry_mode=false (Standard) unverändert:
/api/<majorversion>.<minorversion>/wapi/transaction/execute?dry_mode=true | false

[-> Haupt-Dokumentation]