Die API entdecken mit Postman

Um die API interaktiv zu entdecken, ist die Chrome-Extension Postman sehr gut geeignet.

Konfiguration

Damit Links, welche die API zurückgibt, einfach gefolgt werden kann, sollte die Option “Retain headers on clicking on links” in den Einstellungen von Postman aktiviert werden:

postman-retain-headers

Diese Option stellt sicher, dass einmal konfigurierte HTTP-Header bei Folge-Requests mitgeschickt werden, wenn diese durch das Klicken auf Links in der Response ausgelöst werden. Dies erleichtert so das Navigieren der Struktur mittels der API.

Die Option “Send anonymous usage data to Postman” sollte deaktiviert werden.

Verwendung

Als erstes muss das zu verwendende HTTP Verb für den Request bestimmt werden. Dieses kann über das entsprechende Drop-Down Menü ausgewählt werden. Als nächstes muss im Feld rechts vom ausgewählten HTTP Verb die URL des Objekts eingetragen werden, auf welches ein Request gemacht werden soll:

postman-request

Anschliessend müssen die notwendigen HTTP Header gesetzt werden. Zum einen ist dies der Authorization Header für die Authentisierung mit dem richtigen Benutzer, und zum anderen der Accept Header welcher bewirkt, dass der Request von der API behandelt wird.

Für das Setzen des Authorization Headers gibt es eine eigenes Tab, welches den endültigen Header aus den gewählten Authentisierungsmethode und Benutzernamen + Passwort generiert.

Als Authentisierungsmethode muss “Basic Auth” gewählt werden, und als Benutzer ein existierender und entsprechend berechtigter Benutzer. Nachdem diese Parameter angegeben wurde, kann mittels Klick auf “Update Request” der entsprechende Authorization Header erzeugt und in den vorbereiteten Request übernommen werden.

postman-basic-auth

Im “Headers” Tab muss nun noch der Accept: application/json Header hinzugefügt werden:

postman-headers

Der Request ist nun vorbereitet und kann durch einen Klick auf “Send” abgeschickt werden.

Die Antwort des Servers (Response) erscheint nun unter dem Request. Den Links in den @id Attributen kann nun durch einen Klick gefolgt werden, und Postman bereitet für den angeklickten Link einen weiteren Request mit den den gleichen Headern vor, welcher durch einen Klick auf “Send” wieder abgesendet werden kann.

So lässt sich die Struktur des GEVER-Mandandanten über die API mittels GET Requests sehr einfach navigieren.