Allgemeines

Die Api-Dokumentations-Seite

Zur technischeren Dokumentation der Schnittstellen kommt Swagger/OpenAPI zum Einsatz.

Auf den Api-Dokumentations-Seiten finden sich detailliertere Informationen, die für die Übertragung wichtig sind, wie minimal/maximal Längen von Feldern, erlaubte Werte oder die Angabe ob ein Feld Pflicht ist oder nicht. Zusätzlich gibt es für jedes Feld noch eine Kurze Beschreibung.

Um diese Informationen anzuzeigen kann die gewünschte Methode (hier z.B. Policierung) aufgeklappt werden. Anschließend erfolgt unten rechts ein Klick bei Model. Daraufhin werden die Details sichtbar. Zur besseren Übersicht sollte das JSON herauskopiert und in einem Editor mit Syntax Highlighting eingefügt werden.

Endpunkt-URLs

Um die Endpunkt-URL zu ermitteln kann z.B. einmal ein leere JSON-Objekt {} auf der Api-Dokumentations-Seite () gesendet werden. Die Authentifizierungsabfrage kann abgebrochen werden. Anschließend erscheint unter dem Try it out!-Button die vollständige URL.

Authentifikation

Die Authentifikation findet zweistufig statt.

Im ersten Schritt wird ein Client-Zertifikat benötigt, um überhaupt eine Verbindung mit der WebApi herstellen zu können. Dies stellt nur eine allgemeine Zugangsberechtigung dar (wie eine unpersonalisierte Eintrittskarte). Das Zertifikat wird von der NV-IT ausgestellt.

Zertifikate

Ein Zertifikat wird für den produktiven Service und den Test-Service benötigt. Andernfalls ist ein Zugriff auf die Schnittstellen (auch auf die oben erwähnten Api-Dokumentations-Seiten) nicht möglich.

Die eigentliche Authentifizierung des Nutzers erfolgt dann per HTTP Basic Auth. Der Benutzername ist die Vermittlernummer, dass Kennwort kann beim Maklerservice erfragt werden.

Ist das null oder kann das weg?

Grundsätzlich gilt: Ist ein Feld optional, so kann dieses mit null besetzt oder ganz weggelassen werden. null und weglassen sind für die Schnittstelle identisch.

Falsch jedoch ist, eine leere Zeichenfolge einzusetzen. Dies führt zu Fehlern bei der Validierung.