IntelliJ IDEA HTTP-Client

IntelliJ IDEA Utimate bringt seit einiger Zeit einen integrierten HTTP Client mit. Der IntelliJ IDEA HTTP-Client ist ein voll in die IDE integriertes „besseres curl“ mit den typischen Unterstützungen durch die IDE, wie man sie beim Programmieren nutzt und liebt: Automatische Formatierung, Refactoring, Code-Generierung, …

Der HTTP-Client kommt als Plug-in ist aber standardmäßig aktiviert. Sollte es mal nicht aktiviert sein, kann es in den Settings einfach aktiviert werden:

Das HTTP-Client Plugin im Settings Dialog

HTTP-Requests können auf zwei Arten angelegt werden. Entweder als persistierte Datei im Filesystem, oder als Scratch-File.

Scratch-Files sind nicht Teil eines spezifischen Projekts, sondern eher für temporären, lokalen Code gedacht. Sie werden mit Ctrl+Alt+Shift+Insert und der Auswahl von HTTP Request angelegt.

Eine „normale“ HTTP-Request Datei wird angelegt, indem zweimal hintereinander die Shift Taste oder Strg+shift+A gedrückt und in das Suchfeld HTTP Request eingetippt wird:

Eine neue Datei mit der Endung .http wird erstellt. Es empfiehlt sich dafür entweder ein Verzeichnis direkt beim Code der zu testenden API oder ein Test-Verzeichnis wie src/test/http-requests/ anzulegen.

Ein wichtiger Unterschied zwischen Scratch Files und normalen HTTP-Request ist, dass Scratch Files bei jedem Aufruf eines HTTP-Requests verändert werden, indem der Aufruf und das Ergebnis direkt im File protokolliert werden. Sie sind daher nicht für das Einchecken in einem Git Repository geeignet.

Ein einfacher Request kann folgendermaßen aussehen:

### POST httpbin.org Test-Request
POST https://httpbin.org/post
Content-Type: application/json
 
{"content":"FOOBAR"}

Mit ### beginnt der Request, dahinter sollte ein aussagekräftiger Name stehen.
Dann folgt in der nächsten Zeile die HTTP Methode (GET/POST/PUT/DELETE/…) mit der URI und optional der HTTP-Version.
Anschließend können beliebig viele Header angegeben werden.
Getrennt mit einer Leerzeile folgt dann der Content der übertragen werden soll (optional – entfällt z.B. bei GET).

Kommentare beginnen mit // oder #.

Eine Datei kann mehrere Requests enthalten. Diese können über die bekannten IntelliJ Shortcuts oder die UI einzeln oder getrennt ausgeführt werden:

Wird ein Request (oder alle Requests in der Datei) ausgeführt, werden die Ergebnisse (HTTP-Status, Zeiten, Request und Response) dargestellt und können auch gespeichert werden.

Bei einem Scratch File wird zudem eine Verlinkung auf das Ergebnis in der Datei eingefügt, der mit Strg+Klick geöffnet werden kann (<> 2023-01-09T115903.200.html)

Oft möchte man einen Request gegen verschiedene Umgebungen oder mit unterschiedlichen Parametern ausführen. Damit nicht die URL oder die Parameter direkt im Request manipuliert werden müssen, kann man Environments definieren.

Hierzu einfach oben auf No Environment klicken und dann über Add Environment to Public File… oder Add Environment to Private File… eine neue Datei mit Umgebungskonfigurationen anlegen:

Es wird eine neue Datei mit dem Namen http-client.private.]env.json angelegt, in die dann Key-Value-Paare für die Konfigurationen eingetragen werden können:

{
  "dev-backend": {
    "url": "dev-system.pep-digital.de",
    "port": "8081"
  },
  "local-ide-backend": {
    "url": "localhost",
    "port": "8080"
  }
}

Anschließend können diese Variablen mit {{Platzhaltern}} in den Requests verwendet werden. Die Konfigurationsdateien können wie die .http Dateien in Git eingecheckt und gemeinsam im Team genutzt werden. Hierbei sollte darauf geachtet werden, dass keine Konfigurationsdateien mit Passwörtern in Git eingecheckt werden.

Manchmal möchte man aber auch dynamisch das Ergebnis aus einem Request als Input für einen weiteren Request nutzen.

Das folgende Beispiel zeigt, wie mit dem ersten Request ein Token von einem Authorization-Server geholt und mit dem nächsten Request dieses Token für den Zugriff auf einen Resource-Server genutzt wird:

### request bearer token from authorization server
POST {{authorization-server}}/token
Content-Type: application/x-www-form-urlencoded

username={{username}}&password={{password}}

> {%
  client.global.set("auth_token", response.body.access_token);
%}

### use bearer token in resource-server request
GET http://{{backend-server}}/resource
Authorization: Bearer {{auth_token}}

Mit der Zeile client.global.set("auth_token", response.body.access_token); wird aus der JSON-Repsonse der Wert des Eintrags access_token gelesen und in die Variable auth_token gespeichert.

Diese Variable kann dann beim nächsten Request mit {{auth_token}} wiederverwendet werden.

Der HTTP-Client bietet noch etliche weitere Features, die alle recht gut dokumentiert sind.

Tests für HTTP-Requests sind eine letzte hilfreiche Funktion, die ich hier vorstellen möchte. Tests können nach dem Ausführen des Requests automatisch das Ergebnis prüfen.

Ein möglicher Test ist die Prüfung auf den Status der Response. Dazu wird ein Test einfach unter den Request geschrieben:

> {%
  client.test("Request executed successfully", function() {
    client.assert(response.status === 200, "Response status is not 200");
  });
%}

Das Ergebnis sieht dann folgendermaßen aus, wenn der Test fehlschlägt:

Die komplette Beschreibung des IntelliJ IDEA HTTP-Clients findet sich hier: https://plugins.jetbrains.com/plugin/13121-http-client und hier: https://www.jetbrains.com/help/idea/http-client-in-product-code-editor.html.
Die Request Syntax ist hier detailliert beschrieben: https://www.jetbrains.com/help/idea/exploring-http-syntax.html