Einleitung

Überblick

Die Schnittstelle WebAPI bietet IT-Betreuern am KIT die Möglichkeit, eigene, speziell zugeschnittene Anwendungsprogramme für die Pflege ihrer netzdienste-spezifischen Anwendungsdaten aufzubauen.

Die Schnittstelle setzt auf der Netzdatenbank des SCC (NetDB) auf und ist für eine vollautomatisierte Nutzung auf Basis des heutzutage üblichen textbasierten Datenaustauschformates JSON (JavaScript Object Notation) vorgesehen (s.a. http://de.wikipedia.org/wiki/JavaScript_Object_Notation).

Sie ist ausschließlich über HTTPS erreichbar und kann dadurch mit jeder beliebigen HTTP-Programmbibliothek benutzt werden. Im Rahmen der implementierten Systeme (=Anwendungsbereiche), Objekttypen und Funktionen lassen sich sämtliche Daten durch entsprechende Dienstanforderungen (Requests) sowohl ausgeben bzw. abfragen als auch modifizieren (d.h. im Standardfall Eintragen, Ändern, Löschen). Die konkreten, jeweils versionsspezifischen Informationen und Parameter zu diesen Systemen, Objekttypen und Funktionen sind nicht Bestandteil dieser Dokumentation, sondern über den selbstdokumentierenden Systemdatenbereich bzw. Indexabfragen der WebAPI erreichbar.

Alle nachfolgenden Beispielangaben zu Requests sind auf die Verwendung des Programms ‘curl’ bezogen. Eine einfache, besser lesbare Formatierung der JSON-Ausgabe mit Zeilenumbrüchen und Einrückungen erreicht man z.B. mit ‘curl … | python -m json.tool’.

Zum Testen und Verstehen der API bietet sich das Entwicklungs-Webinterface ‘Swagger’ an. Dort steht in der

• Produktionsumgebung unter https://netvs.scc.kit.edu/swagger
• Testumgebung unter https://netvs-test.scc.kit.edu/swagger
• Entwicklungsumgebung unter https://netvs-devel.scc.kit.edu/swagger

ein API-Browser zur Verfügung.

Generelles

• Basis-URI: https://api.netdb.scc.kit.edu (Details im Hauptteil).
• Alle Funktionen sind über ‘HTTP POST’ erreichbar; Nur-Lesefunktionen sind auch über ‘HTTP GET’ erreichbar.
• Begriffskonventionen zu JSON:
  • JSON-Dict: Objekt bzw. assoziatives Array (Key-Value- bzw. Schlüssel-Wert-Verzeichnis), beginnt mit { und endet mit }.
  • JSON-Array: positionale Liste oder Array: beginnt mit [ und endet mit ].
• Das Eingabe- und Ausgabeformat eines POST-Requests (und das Ausgabeformat eines GET-Requests) ist grundsätzlich JSON.
• Jeder Request ist transaktional, d.h. entspricht einer separaten Datenbank-Transaktion.
• Der erste Fehler, der bei der Ausführung eines Requests auftritt, führt zum Abbruch. Die Transaktion wird dadurch zurückgerollt, d.h. alle in diesem Request erfolgten Datenmodifikationen werden rückgängig gemacht.

Zugang und Registrierung

Auf HTTPS-Ebene findet die Identifizierung und Authentifizierung statt. Hierfür wird ein token-basiertes Authentifizierungsverfahren eingesetzt. Die dazu erforderlichen WebAPI-Token müssen vom Inhaber eines KIT-Benutzerkontos eingerichtet werden. Voraussetzung ist, dass dieses Konto mit einem gleichnamigen NetDB-Benutzerkonto verknüpft ist.

Detailliertere Informationen finden Sie im Hauptteil.