Wer an REST-APIs entwickelt, kann diese im einfachsten Fall mit dem Browser debuggen. Aber sobald man über GET hinaus geht, wird es komplizierter, einen PUT-Request kann man nicht einfach in die Adresszeile eingeben. Postman ist hier eine schöne Lösung, man kann Requests sehr bequem abschicken, und auch in der Cloud verwalten.
Nachteil: Ich habe eine Schnittstelle entwickelt, und mir schöne Test-Requests angelegt. Dann gehe ich in den Urlaub, und Kollege X muss einen Bug fixen. (Ja, ich weiß, unrealistisches Beispiel: mein Code hat selbstverständlich keine Bugs. Aber lass uns zum Spaß mal davon ausgehen, es wäre wirklich so)
Der Kollege muss sich jetzt alle Test-Requests wieder neu anlegen – unnötige Mehrarbeit.
Jetzt kann man natürlich Accounts sharen, sodass der Kollege meine Requests auch sieht. Aber die Requests sind in keiner Versionsverwaltung, irgendwer löscht versehentlich alle Requests, und es gibt kein Backup. BOOM!
Außerdem muss ich alle Request vier Mal anlegen: Für Dev, Int, Staging und Production. Lästig!
Wäre es nicht schön, wenn ich das einfach in meinem Code anlegen könnte? Mit konfigurierbarem Host?
PhpStorm to the rescue – again
Und tatsächlich habe ich das letzte Woche bei einem Kollegen gesehen – genau das geht, und zwar mit PhpStorm Bordmitteln. Crazy shit!
Für unsere Beispiele benutze ich REQ | RES, eine schicke Demo-API mit Fake-Daten.
Fangen wir mit einem einfachen Beispiel an, ich will alle User auflisten. Also lege ich eine neue HTTP-Request Datei an:
Die Datei wird mit ein paar hilfreichen Hilfe-Kommentaren angelegt. Nutzen wir diesen gleich, und legen mittels gtr<tab> einen Get Request an:
Grundeinstellung ist http.
FAIL
HTTP ist sowas von out – wie man daran sieht, dass Strato immer noch richtig Kohle für SSL-Zertifikate sehen will (6 Euro – monatlich – wofür?!) und ohne Root-Server kein LetsEncrypt zulässt. Ein Glück, dass ich zu faul bin, den Provider zu wechseln.
Aber zurück zum Thema:
Ein Klick auf den grünen Play-Button oder <Alt>-Enter auf der URL schickt die Anfrage ab:
Die Antwort wird prettified, aber JSON lässt sich leider nicht einklappen – hier ist noch Luft nach oben.
Drei Raute-Zeichen (###) trennen Abfragen voneinander. In der nächsten Anfrage senden wir mal ein paar Daten:
Und nächster Versuch:
Variablen
Um die Requests jetzt für die verschiedenen Plattformen wieder zu verwenden, kann man mit {{}} Variablen einsetzen:
GET https://{{host}}/api/users/
Welche Hosts zur Verfügung stehen, kann ich in einer JSON-Datei konfigurieren.
Diese Datei muss entweder rest-client.env.json oder http-client.env.json heißen und darf irgendwo im Projekt liegen. Sollten mehrere Dateien vorhanden sein, werden sie gemergt.
{
"development": {
"host": "localhost"
},
"production": {
"host": "reqres.in"
}
}
In der aktuellen Beta kann er sogar den Host ersetzen, wenn keine Variable benutzt wird:
Allerdings ist noch ein Bug drin:
Stories
Da ich in eine File mehrere Requests packen kann, kann ich auch komplexere Abläufe damit gut debuggen, z.B. so:
- POST {{host}}/user/ mit JSON-Daten für Benutzer 1
- POST {{host}}/user/ mit JSON-Daten für Benutzer 2
- POST {{host}}/user/1/relation/2 Benutzer 1 und 2 verknüpfen
- POST {{host}}/user/ mit JSON-Daten für Benutzer 3 anlegen, der mit Benutzer 2 automatisch verknüpft wird
- GET {{host}}/user/1/relation -> Sollte die Daten für Benutzer 2 und 3 zurückgeben
Die Requests kann ich nun nacheinander ausführen und debuggen. Darunter kann ich noch ein paar Aufrufe hinzufügen um die Daten wieder zu löschen.
Debuggen geht am Einfachsten, indem man
?XDEBUG_SESSION_START=PHPSTORM
hinten an die URL hängt.
TIPP
It’s a secret!
Will ich Passwörter nicht ins Repo committen, dann kann ich dafür auch Variablen verwenden:
Authorization: Basic {{user}} {{password}}
User und Password definiere ich dann in der File rest-client.private.env.json, und setze diese in .gitignore. Dann muss jeder nach dem Checkout diese Datei mit den entsprechenden super-secret Passwörtern (Passwort123!) anlegen.
Swagger und Konsorten
Bevor jetzt jemand ruft: “Das mache ich mit Swagger / Apiary / RAML /…!” – Diese Tools gehören selbstverständlich zu jeder REST-API dazu.
Aber: Mit Swagger kann ich einen Beispielrequest schicken, oder benutzerdefinierte Anfragen einfach senden. Ich kann nicht mehrere Testanfragen bereitstellen, keine Gruppierung von CRUD-Anfragen hintereinander setzen, mit denen ich auf einem Testsystem hintereinander einen Wert anlegen, verändern, auslesen und löschen kann.
Ideen?
Wir nutzen das aktuell so, dass wir zu jedem API-Modul einen Folder debug/ anlegen. In diesen kommen Beispiel- und Test-Requests für jeden Endpoint rein, die mit committed werden. Die rest-client.env.json legen wir im Root-Folder ab.
Wie macht Ihr das? Habt Ihr noch mehr Ideen, wie man das nutzen kann? Dann bitte unten kommentieren!
Mehr Informationen zu dem HTTP Client von PhpStorm findet Ihr in der Dokumentation. Dort steht auch u.a. wie man Anfragen von dev und live vergleichen kann oder auf Skripte in die Requests einbauen kann.
Nachtrag 22.11.2019
Inzwischen gibt es von Jetbrains auch ein gutes Video:
Wenn du Postman nicht richtig kennst, solltest du nicht über Postman herziehen.
Bei Postman kann man sein Request-SET auch exportieren/importieren. Oder im Postman Team Workspace speichern.
In Postman kann man auch Env Variablen anlegen und so z.b Steuern das man Requests gegen qa oder staging schickt. Diese Env Variablen kann man auch pro Ordner überschreiben und auch für Parameter und Co. verwenden.
Zitat: “HTTP ist sowas von out”
* Und selber eine Webseite mit HTTP/1 ohne Zertifikat.
* WP als Entwickler zu benutzen ist auch nicht das wahre.
Vielen Dank für Dein Feedback.
Ich kann Deine Kritik allerdings nicht wirklich nachvollziehen. Ich finde “Postman ist hier eine schöne Lösung” nicht darüber herziehen. Warum ich kein HTTPS anbieten kann, steht im Post ebenfalls.
Ich versuche nur aufzuzeigen, dass ein im Code hinterlegtes, von der IDE ansprechbares Interface zur API für mich praktisch ist. Hier bietet Postman nicht die Features, die ich benötige.