Beispiele

Die folgenden Beispiele dienen nur der Veranschaulichung. Sie sind daher inhaltlich als ungültig zu betrachten. Je nach Betriebssystem bzw. Kommandozeileninterpreter (Shell) wird der Backslash ‘\‘ als Shell-Escape-Character verwendet. Eine einfache Formatierung der JSON-Ausgabe mit Zeilenumbrüchen und Einrückungen erreicht man z.B. mit ‘curl … | python -m json.tool’.

Indexabfragen

Die Indexabfragen erlauben es, die gültigen Wertebelegungen der jeweils nächsten Unterebene des URI-Schemas festzustellen.

Versionsindex

  • Ziel:
    • Ausgabe der implementierten Versionsnummern und den darunter verfügbaren Systemen sowie der jedem System zugeordneten semantischen Versionsangabe (Bezeichner “VersionNumIndex”)
    • Ausgabe der Versionsnamen mit den zugeordneten Systemen und numerischen Versionsangaben (Bezeichner “VersionNameIndex”)
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/
  • Antwort:
{
    "VersionNameIndex": {
         "release": {
            "dns": {
                "description": null, 
                "major_number": 1, 
                "minor_number": 0, 
                "status": "aktuelle Version"
            }, 
            "nd": {
                "description": null, 
                "major_number": 1, 
                "minor_number": 0, 
                "status": "aktuelle Version"
            }, 
            "nm": {
                "description": null, 
                "major_number": 1, 
                "minor_number": 0, 
                "status": "aktuelle Version"
            }, 
            "wapi": {
                "description": null, 
                "major_number": 1, 
                "minor_number": 0, 
                "status": "aktuelle Version"
            }
        }
    }, 
    "VersionNumIndex": {
        "1.0": {
            "dns": {
                "description": null, 
                "name": "release", 
                "status": "aktuelle Version"
            }, 
            "nd": {
                "description": null, 
                "name": "release", 
                "status": "aktuelle Version"
            }, 
            "nm": {
                "description": null, 
                "name": "release", 
                "status": "aktuelle Version"
            }, 
            "wapi": {
                "description": null, 
                "name": "release", 
                "status": "aktuelle Version"
            }
        }
    }
}

Systemindex

  • Ziel: Ausgabe aller unter Version 1.0 implementierten Systeme
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/
  • Antwort:
{
    "SystemIndex": {
        "dns": "DNSVS", 
        "nd": "Netzdokumentation", 
        "nm": "Netzmanagement", 
        "wapi": "WebAPI"
    }
}

Objekttypindex

  • Ziel: Ausgabe der in Version 1.0 im System dns implementierten Objekttypen:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/dns/
  • Antwort:
{
    "ObjectTypeIndex": {
        "fqdn": "DNS-Namensobjekte (FQDN) in hierarchischer Struktur", 
        "fqdn_inttype": "systeminterne Typ-Definitionen für FQDN's", 
        "ipaddr": "IP-Adressen", 
        "mgr": "Zuordnung von Betreuer-Accounts zu DNSVS-Bereichen", 
        "record": "DNS-Resource-Records", 
        "record_inttype": "systeminterne Zuordnung zwischen Namenstyp für FQDN's, RR-Typ und Zieldatentyp sowie Eindeutigkeitsmerkmale", 
        "zone_deleg": "Zonendelegationen"
    }
}

Funktionsindex

  • Ziel: Ausgabe der in Version 1.0 im System dns und dem Objekttyp fqdn verfügbaren Funktionen:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/dns/fqdn/
  • Antwort:
{
    "FunctionIndex": {
        "create": {
            "doc": null, 
            "mode": ["write"], 
            "params_dict": {}
        }, 
        "delete": {
            "doc": null, 
            "mode": ["write"], 
            "params_dict": {}
        }, 
        "list": {
            "doc": null, 
            "mode": ["read"], 
            "params_dict": {
                "domain": {
                    "default": null, 
                    "description": "übergeordneter Domainname (FQDN)"
                }, 
                "fqdn": {
                    "default": null, 
                    "description": "DNS-FQDN (Fully Qualified Domain Name)"
                }, 
                "fqdn_regexp": {
                    "default": null, 
                    "description": "Regulärer Ausdruck des Suchmusters für Owner-FQDN's"
                }, 
                "inttype": {
                    "default": [], 
                    "description": "Name der systeminternen DNS-DB-Namenstypdefinition"
                }, 
                "label": {
                    "default": null, 
                    "description": "linker Teil des FQDN's bis zum ersten Punkt"
                }, 
                "label_regexp": {
                    "default": null, 
                    "description": "Regulärer Ausdruck des Suchmusters für Hostnamen (Teil des FQDN bis zum ersten Punkt)"
                }, 
                "listopt_subtree": {
                    "default": "false", 
                    "description": "optional: rekursive Ausgabe, falls 'domain' spezifiziert wurde"
                }, 
                "zone": {
                    "default": null, 
                    "description": "Zonen-Name"
                }
            }
        }, 
        "update": {
            "doc": null, 
            "mode": ["write"], 
            "params_dict": {}
        }
    }
}

Abfragen des Systemdatenverzeichnisses

Ausgabebeispiel mit leerer Key-Value-Attributliste

  • Ziel: Ausgabe der Parameterdaten (für Datenmanipulationen) für System dns, Objekttyp fqdn, Funktion create
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/datadict/list\?sys_name=dns\&ot_name=fqdn\&function_name=create

Die Parameterzeichenkette kann bei curl auch durch den Parameter -d separat (als Request Body) übergeben werden:

curl -E mycertfile.pem -d 'sys_name=dns&ot_name=fqdn&function_name=create' https://www-net.scc.kit.edu/api/1.0/wapi/datadict/list
  • Antwort:
{
    "dns": {
        "ObjectTypeDict": {
            "fqdn": {
                "FunctionDict": {
                    "create": {
                        "ParameterDict": {
                            "description": {
                                "allow_array_context": false,
                                "datatype": {
                                    "description": "Text",
                                    "name": "string"
                                },
                                "description": "Freitext-Info zum FQDN",
                                "returning": {
                                    "new_value": {
                                        "is_defined": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                },
                                "submitting": {
                                    "new_value": {
                                        "data_default": null,
                                        "is_defined": true,
                                        "is_nullable": true
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                }
                            },
                            "fqdn": {
                                "allow_array_context": false,
                                "datatype": {
                                    "description": "Text",
                                    "name": "string"
                                },
                                "description": "DNS-FQDN (Fully Qualified Domain Name)",
                                "returning": {
                                    "new_value": {
                                        "is_defined": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                },
                                "submitting": {
                                    "new_value": {
                                        "data_default": null,
                                        "is_defined": true,
                                        "is_nullable": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                }
                            },
                            "inttype": {
                                "allow_array_context": false,
                                "datatype": {
                                    "description": "Text",
                                    "name": "string"
                                },
                                "description": "Name der systeminternen DNS-DB-Namenstypdefinition",
                                "returning": {
                                    "new_value": {
                                        "is_defined": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                },
                                "submitting": {
                                    "new_value": {
                                        "data_default": null,
                                        "is_defined": true,
                                        "is_nullable": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                }
                            }
                        }
                    }
                },
                "KeyValDepdntObjectTypeDict": {},
                "KeyValDict": {},
                "description": "DNS-Namensobjekte (FQDN) in hierarchischer Struktur"
            }
        },
        "description": "DNSVS"
    }
}

Ausgabebeispiel mit nicht-leerer Key-Value-Attributliste

  • Ziel: Ausgabe der Parameterdaten (für Datenmanipulationen) für System nd, Objekttyp device, Funktion delete
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/datadict/list\?sys_name=nd\&ot_name=device\&function_name=delete
  • Antwort:
{
    "nd": {
        "ObjectTypeDict": {
            "device": {
                "FunctionDict": {
                    "delete": {
                        "ParameterDict": {
                            "fqdn": {
                                "allow_array_context": false,
                                "datatype": {
                                    "description": "Text",
                                    "name": "string"
                                },
                                "description": "DNS-FQDN des ND-Devices",
                                "returning": {
                                    "new_value": {
                                        "is_defined": false
                                    },
                                    "old_value": {
                                        "is_defined": false
                                    }
                                },
                                "submitting": {
                                    "new_value": {
                                        "is_defined": false
                                    },
                                    "old_value": {
                                        "data_default": null,
                                        "is_defined": true,
                                        "is_nullable": false
                                    }
                                }
                            }
                        }
                    }
                },
                "KeyValDepdntObjectTypeDict": {
                    "objecttype_name": "device_type",
                    "system_name": "nd"
                },
                "KeyValDict": {
                    "fw_version": {
                        "datatype": {
                            "description": "Text",
                            "name": "string"
                        },
                        "description": "Firmware-Versionsnummer oder Bezeichnung",
                        "name": "FW-Version"
                    },
                    "gen_single_ii_port_name": {
                        "datatype": {
                            "description": "Text",
                            "name": "string"
                        },
                        "description": "Vorgabe des Mgmt-Ports (L-Port identisch zu P-Port)",
                        "name": "L/P-Port-Name des IP-Interfaces"
                    },
                    "mgmt_vrf_name": {
                        "datatype": {
                            "description": "Text",
                            "name": "string"
                        },
                        "description": "VRF-Name des Management-IP-Interfaces",
                        "name": "Management-VRF"
                    },
                    "os_name": {
                        "datatype": {
                            "description": "Text",
                            "name": "string"
                        },
                        "description": "Betriebssystem, Distribution, Versionsnummer",
                        "name": "Betriebssystem-Bezeichnung"
                    },
                    "snmp_sys_descr": {
                        "datatype": {
                            "description": "Text",
                            "name": "string"
                        },
                        "description": "(System Description via SNMP)",
                        "name": "System Description"
                    }
                },
                "description": "logischer Teil der managebaren (aktiven) Netzkomponenten/Endgeräte"
            }
        },
        "description": "Netzdokumentation"
    }
}
  • Für die Ausgabe von objekttypabhängigen Key-Value-Attributen (s. Dict-Objekt "KeyValDepdntObjectTypeDict") ist eine separate Abfrage des betreffenden Objekttyps erforderlich, da auf dieser Abfrageebene (wapi/datadict) keine weiteren Objekttyp-Attribute spezifizierbar sind.

  • Das Dict-Objekt "KeyValDict" im Beispiel enthält alle Key-Value-Attribute, die für Objekte des Typs device (System nd) existieren. Das Dict-Objekt "KeyValDepdntObjectTypeDict" gibt an, daß zusätzlich eine Abhängigkeit der jeweiligen Key-Value-Attribute zu Objekten des Typs device_type (System nd) besteht. Man bekommt über die separate Abfrage also die Information, welche Key-Value-Attribute für welche Devices (des entsprechenden Device-Typs) definiert sind.

[ -> Ausgabebeispiel]

Abfragen von Anwendungsdaten

Transaktionsplan

  • Ziel: Ausgabe des bereits erstellten Transaktionsplans mit dem Namen ‘my_transaction’
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/list\?name=my_transaction
  • Antwort:
[
    {
        "exec_timestamp": "01.01.2014 06:59:00", 
        "exec_user_list": [
            "yy1234", 
            "zz1234"
        ], 
        "name": "my_transaction", 
        "owner_user": "xx1234", 
        "statement_list": [
            {
                "function_name": "create", 
                "keyval_dict": {}, 
                "objecttype_name": "record", 
                "param_list": [
                    {
                        "name": "data", 
                        "new_value": "192.168.1.1", 
                        "old_value": null
                    }, 
                    {
                        "name": "fqdn", 
                        "new_value": "myhost.kit.test", 
                        "old_value": null
                    }, 
                    {
                        "name": "fqdn_description", 
                        "new_value": "blubb", 
                        "old_value": null
                    }, 
                    {
                        "name": "inttype", 
                        "new_value": "dflt:0100,:,400,A", 
                        "old_value": null
                    }
                ], 
                "system_name": "dns"
            }
        ]
    }
]

Daten, die objekttypabhängige Key-Value-Attribute enthalten

  • Ziel: Ausgabe der Daten für den Device-Typ "r"
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/nd/device_type/list\?name=r
  • Antwort:
[
    {
        "description": "Router", 
        "keyval_dict_list": [
            {
                "datatype": {
                    "description": "Text", 
                    "name": "string"
                }, 
                "default": null, 
                "description": "(System Description via SNMP)", 
                "keyword": "snmp_sys_descr", 
                "name": "System Description", 
                "set_mode_description": "nur durch DevImport änderbar"
            }, 
            {
                "datatype": {
                    "description": "Text", 
                    "name": "string"
                }, 
                "default": null, 
                "description": "Firmware-Versionsnummer oder Bezeichnung", 
                "keyword": "fw_version", 
                "name": "FW-Version", 
                "set_mode_description": "nur durch DevImport änderbar"
            }
        ], 
        "name": "r", 
        "nw_fwd_lvl": 3
    }
]
  • die Key-Value-Attribute (unter Bezeichner "keyval_dict_list") gelten nur für Devices (=WebAPI-Objekte des Typs device) des Device-Typs "r" (=WebAPI-Objekte des Typs device_type).

Eingabe von Anwendungsdaten

Einfache Dateneingabe durch einen URI-basierten Request (1)

Vorbereitung:

Bereitstellen des Request Body als JSON-Code (z.B. als Eingabedatei create_rr.json). Das äußere Array enthält Dict-Objekte, die als Datenmanipulations-Befehle bzw. -Statements zu werten sind. Diese wiederum beinhalten die Dict-Objekte "param_list" und ggf. "keyval_dict". Die verfügbaren Parameter in "param_list" lassen sich durch die Abfrage von Systemdaten ermitteln. Im Beispiel wird Array-Kontext für den letzten Parameter "data" verwendet, d.h. um ein Record-Set eingeben zu können, müssen mehrere Werte für "data" möglich sein.

[
  {
    "param_list":
      [ 
        { "name": "fqdn", "new_value": "myhost.kit.test" },
        { "name": "fqdn_description", "new_value": "blubb" },
        { "name": "inttype", "new_value": "dflt:0100,:,400,A" },
        { "name": "data", "new_value": "192.168.1.1" },
        { "name": "data", "new_value": "192.168.1.2" },
        { "name": "data", "new_value": "192.168.1.3" } 
      ]
  }
]
  • Ziel: die in obiger Datei enthaltenen Eingabedaten als Datenbank-Transaktion ausführen
  • Inhalt: Anlegen eines DNS-A-Record-Sets (Satz von mehreren Records)
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben
curl -d @create_rr.json -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/dns/record/create --header "Content-Type:application/json"
  • Antwort:
    • bei fehlerfreier Ausführung: leeres JSON-Array
    • bei Datenbank-Fehlern: z.B. Eindeutigkeitsverletzung durch wiederholtes Ausführen derselben Transaktion bei ansonsten unverändertem Datenbestand:
{
    "error": {
        "data": {
            "code": "SUBCODE-00012", 
            "code_descr": "[DNS] RR schon vorhanden", 
            "oracle_error_string": "ORA-00001: unique constraint (NETADMIN.DNS_RR_DST_A_UNQ_IDX) violated\nORA-06512: at \"NETADMIN.DNS\", line 5943\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 541\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 1518\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3323\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3651\nORA-06512: at \"NETADMIN.WAPI\", line 94\nORA-06512: at \"NETADMIN.WAPI\", line 255\nORA-06512: at \"NETADMIN.WAPI\", line 393\nORA-06512: at line 3\n", 
            "text_descr": "Ein DNS-Resource-Record mit gleichlautenden Parametern f\u00fcr FQDN, Typ, Ziel (RR-Data) ist bereits vorhanden."
        }, 
        "traceback": [
            {
                "function": "dns.exec_insert_rr_osd", 
                "param": {
                    "dns.fqdn.fqdn": "myhost.kit.test.", 
                    "dns.record.dst_at": "4", 
                    "dns.record.dst_ipaddr": "192.168.1.1", 
                    "dns.record.rr_data": null, 
                    "dns.record_inttype.name": "dflt:0100,:,400,A", 
                    "dns.record_inttype.target_addr_inttype": "4"
                }
            }
        ], 
        "type": {
            "code": "ORA-20100", 
            "code_descr": "unq_constraint_violation", 
            "text_descr": "Dateneindeutigkeit verletzt"
        }
    }
}

Einfache Dateneingabe durch einen URI-basierten Request (2)

Vorbereitung:

Bereitstellen des Request Body als JSON-Code (z.B. als Eingabedatei create_lease.json). Das äußere Array enthält Dict-Objekte, die als Datenmanipulations-Befehle bzw. -Statements zu werten sind. Diese wiederum beinhalten die Dict-Objekte "param_list" und ggf. "keyval_dict". Die verfügbaren Parameter in "param_list" lassen sich durch die Abfrage von Systemdaten ermitteln.

[
  {
    "param_list":
      [
        { "name": "subnet_cidr_mask", "new_value": "192.168.1.1/24" },
        { "name": "subnet_is_stat_routed", "new_value": false },
        { "name": "mac_address", "new_value": "0a:0b:0c:0d:0e:0f" },
        { "name": "is_static_addr", "new_value": true },
        { "name": "always_match_by_mac_addr", "new_value": false },
        { "name": "ip_address", "new_value": "192.168.1.100" },
        { "name": "adm_status_descr", "new_value": "statische dhcp-adresszuordnung" }
      ]
  }
]
  • Ziel: die in obiger Datei enthaltenen Eingabedaten als Datenbank-Transaktion ausführen.
  • Inhalt: Anlegen eines DHCP-Lease-Datensatzes.
  • Die in obiger Datei nicht enthaltenen, aber erforderlichen Daten für System, Objekttyp und Funktion werden in der URI-Adresse übergeben. Als Antwortparameter wird "id" übergeben (wurde im Request nicht angegeben, da automatisch durch die Datenbank erzeugt). Der Bezeichner "statement_pos" gibt die 1-basierte Position des Statements (äußeres Dict-Objekt im Array) im Transaktionsplan an, auf das sich der bzw. die Antwortparameter beziehen.
curl -d @create_lease.json -E mycertfile.pem https://www-net.scc.kit.edu/api/1.2/dhcp/lease/create --header "Content-Type:application/json"
  • Antwort bei fehlerfreier Ausführung:
[
    {
        "function_name": "create",
        "objecttype_name": "lease",
        "param_list": [
            {
                "name": "id",
                "new_value": "26",
                "old_value": null
            }
        ],
        "statement_pos": 1,
        "system_name": "dhcp"
    }
]
  • Antwort bei Datenbank-Fehlern: z.B. Eindeutigkeitsverletzung durch wiederholtes Ausführen derselben Transaktion bei ansonsten unverändertem Datenbestand:
{
    "error": {
        "data": {
            "code": "SUBCODE-00000",
            "code_descr": "[CNTL] Ein DHCP-Lease-Datensatz mit den angegebenen Werten für die eindeutigen Felder ist schon vorhanden.",
            "oracle_error_string": "ORA-00001: unique constraint (NETADMIN.UNQ_DHCP_LEASE_ADDR) violated\nORA-06512: at \"NETADMIN.DHCP_WAPI_1_2\", line 806\nORA-06512: at \"NETADMIN.DHCP_WAPI_1_2\", line 1025\nORA-06512: at \"NETADMIN.DHCP_WAPI_1_2\", line 1119\nORA-06512: at \"NETADMIN.DHCP_WAPI_1_2\", line 1258\nORA-06512: at \"NETADMIN.WAPI\", line 128\nORA-06512: at \"NETADMIN.WAPI\", line 476\nORA-06512: at \"NETADMIN.WAPI\", line 637\nORA-06512: at line 3\n",
            "text_descr": "Ein DHCP-Lease-Datensatz wird durch das Feld \"DHCP_LEASE.DNS_ADDR_KEY_NR\" eindeutig identifiziert."
        },
        "traceback": [
            {
                "function": "dhcp_wapi_1_2.do_insert_lease",
                "param": {
                    "dhcp.lease.accept_requested_hostname": null,
                    "dhcp.lease.adm_status_descr": "statische dhcp-adresszuordnung",
                    "dhcp.lease.always_match_by_mac_addr": "false",
                    "dhcp.lease.client_identifier": null,
                    "dhcp.lease.fqdn": null,
                    "dhcp.lease.ip_address": "192.168.1.100",
                    "dhcp.lease.is_static_addr": "true",
                    "dhcp.lease.leasetime": null,
                    "dhcp.lease.mac_address": "0a:0b:0c:0d:0e:0f",
                    "dhcp.lease.subnet_cidr_mask": "192.168.1.1/24",
                    "dhcp.lease.subnet_is_stat_routed": "false"
                }
            }
        ],
        "type": {
            "code": "ORA-20100",
            "code_descr": "unq_constraint_violation",
            "text_descr": "Dateneindeutigkeit verletzt"
        }
    }
}

Komplexe Dateneingabe über einen temporären Transaktionsplan

Vorbereitung:

Bereitstellen des Request Body als JSON-Code (z.B. als Eingabedatei create_ta_immediate.json). Das äußere Array enthält Dict-Objekte, die als Datenmanipulations-Befehle bzw. -Statements zu werten sind. Die verfügbaren Parameter in "param_list" lassen sich durch die Abfrage von Systemdaten ermitteln:

[
  {
    "system_name": "dns",
    "objecttype_name": "fqdn",
    "function_name": "update",
    "param_list":
      [
        { "name": "fqdn", "old_value": "testdevice.scc.kit.test", "new_value": "testdevice.tmn.scc.kit.test" },
        { "name": "description", "new_value": "moved to tmn-subdomain" } 
      ]
  },
  {
    "system_name": "dns",
    "objecttype_name": "record",
    "function_name": "create",
    "param_list":
      [
        { "name": "fqdn", "new_value": "testdevice.scc.kit.test" },
        { "name": "inttype", "new_value": "alias:0000,dflt:0100,011,CNAME" },
        { "name": "data", "new_value": "testdevice.tmn.scc.kit.test" }
      ]
  }
]
  • Ziel: unmittelbare Ausführung der Befehle des in obiger Datei enthaltenen temporären Transaktionsplans
  • Inhalt:
    • Ändern eines DNS-Hostnamens (Verschieben in die Subdomain 'tmn')
    • Anlegen eines DNS-CNAME-Records mit dem FQDN des bisherigen Hostnamens
curl -d @create_ta_immediate.json -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run_immediate --header "Content-Type:application/json"
  • Antwort:
    • bei fehlerfreier Ausführung: leeres JSON-Array
    • bei Datenbank-Fehlern: z.B. Eindeutigkeitsverletzung durch wiederholtes Ausführen derselben Transaktion bei ansonsten unverändertem Datenbestand:
{
    "error": {
        "data": {
            "code": "SUBCODE-00015", 
            "code_descr": "[DNS] Namensobjekt in Domain schon vorhanden", 
            "oracle_error_string": "ORA-00001: unique constraint (NETADMIN.UNQ_DNS_NTREE_NAME) violated\nORA-06512: at \"NETADMIN.DNS\", line 1368\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 1379\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 1550\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3418\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3660\nORA-06512: at \"NETADMIN.WAPI\", line 95\nORA-06512: at \"NETADMIN.WAPI\", line 256\nORA-06512: at \"NETADMIN.WAPI\", line 394\nORA-06512: at line 3\n"
        }, 
        "traceback": [
            {
                "function": "dns.exec_update_pqdn", 
                "param": {
                    "dns.fqdn.name": "testdevice", 
                    "dns.fqdn.parent_fqdn": "tmn.scc.kit.test.", 
                    "dns.fqdn_inttype.description": "Alias (terminal FQDN)"
                }
            }
        ], 
        "type": {
            "code": "ORA-20100", 
            "code_descr": "unq_constraint_violation", 
            "text_descr": "Dateneindeutigkeit verletzt"
        }
    }
}

Komplexe Dateneingabe über einen nicht-temporären Transaktionsplan

Vorbereitung:

Bereitstellen des Request Body als JSON-Code (z.B. als Eingabedatei create_ta.json). Das äußere Array enthält Dict-Objekte, die als Transaktionspläne zu werten sind. Das im Dict-Objekt "statement_list" (des Transaktionsplans) enthaltene Array enthält Dict-Objekte, die als Datenmanipulations-Befehle bzw. -Statements zu werten sind. Die verfügbaren Parameter in "param_list" lassen sich durch die Abfrage von Systemdaten ermitteln:

[
  {
    "name": "my_transaction",
    "exec_timestamp": "1.1.2014 06:59:00",
    "exec_user_list": ["yy1234", "zz1234"],
    "statement_list":
      [
        {
          "system_name": "dns",
          "objecttype_name": "record",
          "function_name": "create",
          "param_list":
            [
              { "name": "fqdn", "new_value": "testdevice.scc.kit.test" },
              { "name": "fqdn_description", "new_value": "blubb" },
              { "name": "inttype", "new_value": "dflt:0100,:,400,A" },
              { "name": "data", "new_value": "192.168.1.1" }
            ],
          "keyval_dict": {}
        },
        {
          "system_name": "nd",
          "objecttype_name": "modul",
          "function_name": "create",
          "param_list":
            [
              { "name": "name", "new_value": "testdevice-2" },
              { "name": "type", "new_value": "A2H124-24" },
              { "name": "bldg", "new_value": "20.21" },
              { "name": "room", "new_value": "001.2" }
            ],
          "keyval_dict":
            {
              "stack_pos": 2
            }
        },
        {
          "system_name": "nd",
          "objecttype_name": "modul",
          "function_name": "create",
          "param_list":
            [
              { "name": "name", "new_value": "testdevice-3" },
              { "name": "type", "new_value": "A2H124-24" },
              { "name": "bldg", "new_value": "20.21" },
              { "name": "room", "new_value": "001.2" }
            ],
          "keyval_dict":
            {
              "stack_pos": 3
            }
        },
        {
          "system_name": "nd",
          "objecttype_name": "MDL2DEV",
          "function_name": "create",
          "param_list":
            [
              { "name": "DEV_FQDN", "new_value": "testdevice.scc.kit.test" },
              { "name": "MDL_NAME", "new_value": "testdevice-2" }
            ],
          "keyval_dict": { }
        },
        {
          "system_name": "nd",
          "objecttype_name": "MDL2DEV",
          "function_name": "create",
          "param_list":
            [
              { "name": "DEV_FQDN", "new_value": "testdevice.scc.kit.test" },
              { "name": "MDL_NAME", "new_value": "testdevice-3" }
            ],
          "keyval_dict": { }
        }
      ]
  }
]
  • Ziel: Eingabe des in obiger Datei enthaltenen Transaktionsplans mit dem Namen "my_transaction"
  • Inhalt:
    • Erzeugen der Daten für “Anlegen eines DNS-A-Records”
    • Erzeugen der Daten für “Anlegen zweier ND-Module (physikalische Netzkomponenten)”
    • Erzeugen der Daten für “Anlegen zweier ND-MDL2DEV-Einträge (Zuordnen von ND-Modulen zu DNS-FQDN’s)”
curl -d @create_ta.json -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/create --header "Content-Type:application/json"
  • Antwort: leeres JSON-Array

Transaktionsplan als Datenbank-Transaktion ausführen

  • Ziel: die im Transaktionsplan enthaltenen Änderungsdaten als Datenbank-Transaktion ausführen
  • Inhalt:
    • Anlegen eines DNS-A-Records
    • Anlegen zweier ND-Module (physikalische Netzkomponenten)
    • Anlegen zweier ND-MDL2DEV-Einträge (Zuordnen von ND-Modulen zu DNS-FQDN’s)
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=my_transaction
  • Antwort:
    • bei fehlerfreier Ausführung: leeres JSON-Array
    • bei Datenbank-Fehlern: z.B. Eindeutigkeitsverletzung durch wiederholtes Ausführen derselben Transaktion bei ansonsten unverändertem Datenbestand:
{
    "error": {
        "data": {
            "code": "SUBCODE-00012", 
            "code_descr": "[DNS] RR schon vorhanden", 
            "oracle_error_string": "ORA-00001: unique constraint (NETADMIN.DNS_RR_DST_A_UNQ_IDX) violated\nORA-06512: at \"NETADMIN.DNS\", line 5943\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 541\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 1518\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3323\nORA-06512: at \"NETADMIN.DNS_WAPI_1_0\", line 3651\nORA-06512: at \"NETADMIN.WAPI\", line 94\nORA-06512: at \"NETADMIN.WAPI\", line 255\nORA-06512: at \"NETADMIN.WAPI\", line 376\nORA-06512: at line 3\n", 
            "text_descr": "Ein DNS-Resource-Record mit gleichlautenden Parametern für FQDN, Typ, Ziel (RR-Data) ist bereits vorhanden."
        }, 
        "traceback": [
            {
                "function": "dns.exec_insert_rr_osd", 
                "param": {
                    "dns.fqdn.fqdn": "testdevice.scc.kit.test.", 
                    "dns.record.dst_at": "4", 
                    "dns.record.dst_ipaddr": "192.168.1.1", 
                    "dns.record.rr_data": null, 
                    "dns.record_inttype.name": "dflt:0100,:,400,A", 
                    "dns.record_inttype.target_addr_inttype": "4"
                }
            }
        ], 
        "type": {
            "code": "ORA-20100", 
            "code_descr": "unq_constraint_violation", 
            "text_descr": "Dateneindeutigkeit verletzt"
        }
    }
}

Versionsangaben

Numerische Versionsangabe

Angabe durch URI

  • Version: 1.0 für die Ausgabe von DNS-Records:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/dns/record/list
  • Version: 1.1 für die Ausgabe von DNS-Records:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.1/dns/record/list

Angabe bei Transaktionsplan-Aufrufen

  • für alle Transaktionsbefehle im System dns Version 1.1 verwenden und für solche im System nd Version 1.2 verwenden; für alle übrigen Transaktionsbefehle gilt die numerische Version im URI:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v_dns=1.1\&v_nd=1.2
  • für System dns Version 1.1 verwenden, alle anderen Systeme verwenden die numerische Version im URI:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v_dns=1.1

Semantische Versionsangabe

  • für alle Transaktionsbefehle im System dns Version release verwenden und für solche im System nd Version beta verwenden; für alle übrigen Transaktionsbefehle gilt die numerische Version im URI:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v_dns=release\&v_nd=beta
  • für alle Systeme Version release verwenden:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v=release
  • für System dns Version beta verwenden, alle anderen Systeme verwenden die numerische Version im URI:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v_dns=beta

Versionsangabe durch Versionsparameter in der Parameterzeichenkette

  • für alle Transaktionsbefehle im System dns Version release verwenden und für solche im System nd Version 1.1 verwenden; für alle übrigen Transaktionsbefehle gilt die numerische Version im URI:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/1.0/wapi/transaction/run\?name=test-ta-compound\&v_dns=release\&v_nd=1.1

Versionsvergleiche (erst ab Version 2.0)

  • Ziel: vollständige Ausgabe der Versionsunterschiede im Systemindex von 2.0 nach 2.1:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/2.0/\?diff_version=2.1
  • Antwort:
{
    "+": {}, 
    "-": {}, 
    "<>": {
        "SystemIndex": {
            "+": {
                "dhcp": "DHCP"
            }, 
            "-": {}, 
            "<>": {}, 
            "==": {
                "dns": "DNSVS", 
                "nd": "Netzdokumentation", 
                "nm": "Netzmanagement", 
                "wapi": "WebAPI"
            }
        }
    }, 
    "==": {}
}
  • Ziel: vereinfachte Ausgabe der Versionsunterschiede im Systemdatenverzeichnis für den Objekttyp modul von 2.0 nach 2.1:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/2.0/wapi/datadict/list\?diff_version=2.1\&strict_mode=false\&ot_name=modul
  • Antwort:
{
    "<>": {
        "nd": {
            "<>": {
                "ObjectTypeDict": {
                    "<>": {
                        "modul": {
                            "<>": {
                                "FunctionDict": {
                                    "<>": {
                                        "create": {
                                            "<>": {
                                                "ParameterDict": {
                                                    "+": {
                                                        "new_param": {
                                                            "allow_array_context": false,
                                                            "datatype": {
                                                                "description": "Boolean (true/false)",
                                                                "name": "boolean"
                                                            },
                                                            "description": "neuer Parameter",
                                                            "returning": {
                                                                "new_value": {
                                                                    "is_defined": false
                                                                },
                                                                "old_value": {
                                                                    "is_defined": false
                                                                }
                                                            },
                                                            "submitting": {
                                                                "new_value": {
                                                                    "data_default": null,
                                                                    "is_defined": true,
                                                                    "is_nullable": true
                                                                },
                                                                "old_value": {
                                                                    "is_defined": false
                                                                }
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

  • Ziel: Ausgabe der Versionsunterschiede in der Datenstruktur für die Funktion dns/record_inttype/list (Standard-Funktionsname für den Aufruf von list_datastructure) von 2.0 nach 2.1:
curl -E mycertfile.pem https://www-net.scc.kit.edu/api/2.0/dns/record_inttype/list_datastructure\?diff_version=2.1
  • Antwort:
{
    "+": {},
    "-": {},
    "<>": {},
    "==": {
        "0": {
            "description": null,
            "name": null,
            "owner_fqdn_auto_dml": {
                "description": null,
                "value": null
            },
            "owner_fqdn_inttype": null,
            "owner_fqdn_uniqueness": {
                "description": null,
                "value": null
            },
            "record_type": null,
            "target_addr_inttype": {
                "description": null,
                "value": null
            },
            "target_uniqueness": {
                "description": null,
                "value": null
            }
        }
    }
}

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. Im vorliegenden Beispiel ist die Datenstruktur in beiden Versionen identisch.