REST-APIs mit Bruno testen
Der Neue
Veröffentlicht in Ausgabe 08/2024 - PRAXIS
Eine REST-API ist eine auf HTTP basierende Schnittstelle, die verteilte Methodenaufrufe mit einer speziellen Systematik ermöglicht. Stellen Sie sich nun als Beispiel einen REST-basierten Webdienst vor, der Nachrichten von entsprechenden Portalen abruft und für Sie thematisch aufbereitet. Als Benutzer können Sie allein durch das Hinzufügen der URL eines weiteren Portals zusätzliche Quellen anbinden. Damit die Komponenten dieser großen Anwendung nun miteinander kommunizieren können, müssen natürlich die exakten URLs der Ressourcen, die möglichen Aktionen (Verben), aber auch die Struktur der Daten dokumentiert und eindeutig sein. Aus dem Dokumentationswerkzeug Swagger [1] entstand dafür 2016 die OpenAPI-Spezifikation [2] für die standardisierte Dokumentation von REST-Schnittstellen.
Heute ist die REST-Kommunikation längst de-facto Standard für Anwendungen in allen operativen Bereichen eines Unternehmens. Ihr Produktionsmanagement bindet darüber die Bestellprozesse der Zulieferer an, Ihr Zeitmanagement übermittelt die Arbeitszeiten direkt an die Personalbuchhaltung und Ihr IT-Security-Dashboard sammelt darüber alle relevanten Informationen der angeschlossenen Systeme. Da kommen jeden Tag einige Verbindungen in Ihrem Netzwerk zusammen. Um zu verstehen, wie eine spezifische API funktioniert, müssen Sie schon mal einen Blick hineinwerfen. Viele Unternehmen betreiben entsprechende Middleware-Produkte für das Management der API-Benutzung. Diese erfordert die Konfiguration und Freigabe der Endpunkte und möglicherweise auch der ausgetauschten Daten.
Das vermutlich bekannteste Tool für die (manuelle) Prüfung von API-Endpunkten nennt sich Postman und ist bereits seit 2012 am Markt. IT-Sicherheitsverantwortliche nutzen die Software für die sichere Integration in das Firmenumfeld ebenso wie Anwendungsentwickler von RESTKomponenten für die Konzeption, Entwicklung und das Debugging der eigenen API. Bereits im letzten Jahr ist Postman für das obligatorische Einbinden der Cloudservices und die Übertragung der Projektdaten in die Cloud des Anbieters in die Kritik geraten.
Eine REST-API ist eine auf HTTP basierende Schnittstelle, die verteilte Methodenaufrufe mit einer speziellen Systematik ermöglicht. Stellen Sie sich nun als Beispiel einen REST-basierten Webdienst vor, der Nachrichten von entsprechenden Portalen abruft und für Sie thematisch aufbereitet. Als Benutzer können Sie allein durch das Hinzufügen der URL eines weiteren Portals zusätzliche Quellen anbinden. Damit die Komponenten dieser großen Anwendung nun miteinander kommunizieren können, müssen natürlich die exakten URLs der Ressourcen, die möglichen Aktionen (Verben), aber auch die Struktur der Daten dokumentiert und eindeutig sein. Aus dem Dokumentationswerkzeug Swagger [1] entstand dafür 2016 die OpenAPI-Spezifikation [2] für die standardisierte Dokumentation von REST-Schnittstellen.
Heute ist die REST-Kommunikation längst de-facto Standard für Anwendungen in allen operativen Bereichen eines Unternehmens. Ihr Produktionsmanagement bindet darüber die Bestellprozesse der Zulieferer an, Ihr Zeitmanagement übermittelt die Arbeitszeiten direkt an die Personalbuchhaltung und Ihr IT-Security-Dashboard sammelt darüber alle relevanten Informationen der angeschlossenen Systeme. Da kommen jeden Tag einige Verbindungen in Ihrem Netzwerk zusammen. Um zu verstehen, wie eine spezifische API funktioniert, müssen Sie schon mal einen Blick hineinwerfen. Viele Unternehmen betreiben entsprechende Middleware-Produkte für das Management der API-Benutzung. Diese erfordert die Konfiguration und Freigabe der Endpunkte und möglicherweise auch der ausgetauschten Daten.
Das vermutlich bekannteste Tool für die (manuelle) Prüfung von API-Endpunkten nennt sich Postman und ist bereits seit 2012 am Markt. IT-Sicherheitsverantwortliche nutzen die Software für die sichere Integration in das Firmenumfeld ebenso wie Anwendungsentwickler von RESTKomponenten für die Konzeption, Entwicklung und das Debugging der eigenen API. Bereits im letzten Jahr ist Postman für das obligatorische Einbinden der Cloudservices und die Übertragung der Projektdaten in die Cloud des Anbieters in die Kritik geraten.
Als freie und quelloffene Alternative wird von der Community schnell das seit Herbst 2022 entwickelte Bruno [3] ausgemacht. Damit erhalten API-Entwickler eine GUI-Anwendung, die einen ähnlichen Funktionsumfang wie Postman bietet und perspektivisch weiterhin als off-line-only Anwendung verwendbar sein soll. Das bedeutet nicht, dass die Entwickler um Bruno nicht mittlerweile auch kommerzielle Interessen verfolgen. Neben der Grundversion können Sie als Verbraucher oder Unternehmen mit der Golden und der Ultimate Edition weitere Features kostenpflichtig erwerben.
Bruno im Einsatz
Bruno läuft unter den drei bekannten Betriebssystemen und Sie erhalten für alle fertige Binärpakete zum Download [4]. Unter Linux werden Debian-basierte Distributionen direkt unterstützt, für alle anderen bieten die Entwickler ein Binary im AppImage-Format an. Der Einsatz damit klappt wunderbar, alle benötigten Abhängigkeiten sind bereits Teil dieses Images.
Damit Sie bei Ihren ersten Schritten nicht direkt gegen ein kritisches Produktivsystem testen müssen, verwenden wir das von den Swagger- und OpenAPI-Entwicklern bereitgestellte Testsystem in Form einer fiktiven Zoohandlung. Die Dokumentation der API – natürlich im OpenAPI-Format – finden Sie unter [5]. Wenn Sie mögen, können Sie den Endpunkt des Zoogeschäfts auch herunterladen und lokal betreiben [6], in unserem Beispiel verwenden wir aber der Einfachheit halber die Onlinevariante.
Erstellen Sie zunächst ein neues Projekt, indem Sie auf die drei Punkte neben dem Hunde-Icon klicken und "Create Collec-tion" auswählen. Vergeben Sie einen ansprechenden Namen und legen Sie die Collection an. Mit einem Klick auf die drei Punkte neben dem Projektnamen können Sie mit "New Request" eine neue Anfragemaske öffnen. Verwenden Sie für unser Beispiel den Namen "Verfügbare Tiere", geben Sie das HTTP-Verb "GET" an und die URL "https://petstore3.swagger.io/api/v3/pet/findByStatus" in den Dialog ein.
Damit möchten wir die verfügbaren Tiere anzeigen. In der Dokumentation des Zoohandels erkennen Sie die möglichen Parameter für diese Abfrage, mit "status= available" erhalten Sie etwa alle derzeit verfügbaren Tiere. Im Abfragefenster, wie im Bild gezeigt, können Sie dafür unter Query weitere Parameter hinzufügen. Mit einem Klick auf das Pfeilsymbol neben der URL senden Sie die Abfrage ab. Das Ergebnis sehen Sie im rechten Fensterbereich, offenbar sind aktuell noch einige wilde Tiere verfügbar.
Natürlich können Sie nicht nur einzelne Parameter für den Query-String angeben. Um dem Markt ein weiteres Tier hinzuzufügen, erstellen wir eine neue Anfrage mit der URL https://petstore3.swagger. io/api/v3/pet. Die Informationen aus Listing 1 fügen Sie der POST-Anfrage hinzu, indem Sie im Menüpunkt "Body" JSON auswählen und den Inhalt dort einfügen. Nach dem Absenden der Anfrage sehen Sie im Ergebnisfenster "200 OK" in grüner Schrift und das von Ihnen angelegte Tier in der Antwortanzeige.
Ergänzung der POST-Anfrage
{
"accept": {
"server_time": {
"seconds": 1716370731,
"nanoseconds": 137298080,
"iso8601": "20240522093851Z",
"localtime": "May 22 09:38:51"
},
[...]
}
Nachdem Sie das Tier hinzugefügt haben, können Sie es unter "https://petstore3. swagger.io/api/v3/pet/1337" wieder abfragen. Die "1337" steht als Identifikator der Ressource, den Sie in den POST-Daten gesetzt haben. Ein bereits vorhandenes Tier mit derselben ID wird entsprechend aktualisiert.
Automatisieren und testen
Wenn Sie für Ihre Anwendung alle relevanten Abfragen konfiguriert haben, können Sie diese mithilfe des Bruno-Runners in der entsprechenden Reihenfolge ausführen lassen. Dabei werden alle der Collection zugehörigen Abfragen wie im linken Menü der Anwendung durchlaufen. Hier lässt sich auch die Reihenfolge ändern, indem Sie die Einträge einfach an andere Positionen ziehen.
Wenn Sie regelmäßig in denselben Umgebungen und Projekten arbeiten, können Sie rechts oben im Fenster Einstellungen für Ihr Environment festlegen. Hier richten Sie etwa API-Keys oder Basis-URLs als Variablen ein, sodass Sie schnell von Development-Umgebungen zum Beispiel in Staging oder Produktivumgebungen wechseln können, ohne alle Anfragen neu hinterlegen zu müssen. Im Header nutzen Sie den API-Key dann etwa mit "{{apikey}}" und die Basis-URL im Adressfeld mit "{{baseurl}}".
Wenn Sie dynamische Inhalte benötigen, bietet Ihnen Bruno die Möglichkeit, mit JavaScript kleine Skripte zu schreiben. Unter "Script" finden Sie dafür zwei Eingabefelder; das obere wird vor der Anfrage ausgeführt und das untere nach dem Erhalt der Antwort vom Server. Unter dem Punkt "Tests" erstellen Sie zur Automatisierung Skripte im Stil von Unit-Tests mit unterschiedlichen Eingaben und entsprechender Prüfung der Antworten.
Fazit
REST-APIs bestimmen in vielen IT-Umgebungen die Kommunikation innerhalb von Anwendungen. Als Verantwortlicher für IT-Sicherheit geben Sie die Nutzung externer Schnittstellen frei und testen Ihre eigenen internen Schnittstellen. Der Security-Tipp in diesem Monat hat Ihnen mit Bruno eine günstige Offline-Alternative zum etablierten Postman vorgestellt.
(dr)
Link-Codes
[1] Swagger: https://swagger.io/
[2] OpenAPI-Spezifikation: https://www.postman.com/
[3] Bruno: https://www.usebruno.com/
[4] Bruno-Binärpakete zum Download: https://www.usebruno.com/downloads
[5] Dokumentation der API: https://petstore3.swagger.io/
[6] Beispiel-Endpoint herunterladen: https://github.com/swagger-api/swagger-petstore