Tipps & Tricks

Signierte Requests mit Postman erstellen

Aufgabe

Kommunikation zwischen Makaira API und Shop prüfen

Lösung

Mit Postman ist es möglich die mit dem Shared-Secret signierten Requests zwischen Shop und Makaira-API zu überprüfen.

Dazu wird ein POST Request an den vom Shop bereitgestellten Endpunkt gesendet, z.B. <shopurl>?cl=makaira_connect_endpoint im Oxid Shop

Es empfiehlt sich dafür eine Environment-Konfiguration mit folgenden Variablen anzulegen

nonce:123456
secret:<shared secret>
requestHash:someValueThatWillBeOverridden

Folgende Header werden benötigt

Content-Type:application/json
X-Makaira-Nonce:{{nonce}}
X-Makaira-Hash:{{requestHash}}

Mit einem Pre-request Script erfolgt die Generierung des Hash anhand des aktuellen Request-Body

var nonce = postman.getEnvironmentVariable("nonce");
var secret = postman.getEnvironmentVariable("secret");

var hashString = nonce + ':' + request.data;
var hash = CryptoJS.HmacSHA256(hashString, secret);

postman.setEnvironmentVariable("requestHash", hash);

Beispiel: Body für die Prüfung der Update Daten

{"action":"getUpdates","since":0,"count":10,"language":"de"}

Signierung der API-Requests im Shop

Aufgabe

Requests direkt an die Makaira API schicken, ohne Verwendung des Connect-Moduls

Lösung

Die Kommunikation mit der API ist über signierte Requests gesichert. Die Signatur wird als Hash über den Request Body und einer zufällig generierten Nonce mittels eines geteilten Secrets gebildet. Die Header X-Makaira-Nonce und X-Makaira-Hash müssen mit der Request übermittelt werden.

PHP-Beispiel zur Generierung der Header
<?php

/**
 * Execute a HTTP request to the remote server
 *
 * @param mixed  $body         request body
 * @param string $sharedSecret secret shared between client and application
 *
 * @return array
 */
public function generateSignatureHeaders($body = null, $sharedSecret)
{
    $nonce = mt_rand(0, mt_getrandmax());
    $hash = hash_hmac('sha256', $nonce . ':' . $body, $sharedSecret);
    $headers[] = 'X-Makaira-Nonce: ' . $nonce;
    $headers[] = 'X-Makaira-Hash: ' . $hash;

    return $headers;
}

Steuerung der ES-Indizes über die Makaira-API

Aufgabe

Wechseln oder Löschen von ElasticSearch-Indizes über die Makaira-API

Lösung

Makaira ermöglicht das Manipulieren der ElasticSearch-Indizes über die bereitgestellte API.

Als Endpunkt wird die Route <makaira-url>/indices bereitgestellt.

Die Requests zur Interaktion mit der API benötigen zur Verifizierung einen Basic-Auth-Header aus den Login-Daten für die Makaira-Instanz.

Zur Identifikation des relevanten Index kann dessen Alias - zu finden im Makaira unter „Index-Konfiguration“ - verwendet werden, z.B. stage_passive_de.

Löschen eines Index

Hinweis: Beim Löschen sollte beachtet werden nur passive Indizes zu löschen. Der Importer sorgt dafür, dass diese automatisch neu angelegt werden.

curl -X DELETE \
  https://<CUSTOMER>.makaira.io/indices/stage_passive_de \
  -H 'Authorization: Basic <BASIC-AUTH> \
  -H 'Content-Type: application/json'

Aktivieren eines passiven Index

Hinweis: Das Aktivieren eines passiven Index schaltet immer den derzeit aktiven Index der gewählten Sprache auf inaktiv.

curl -X PUT \
  https://<CUSTOMER>.makaira.io/indices/stage_passive_de/active \
  -H 'Authorization: Basic <BASIC-AUTH> \
  -H 'Content-Type: application/json'

Status (Revision) eines Index

Der Request zur Abfrage des Index-Status hat grundlegend die gleiche Struktur wie die vorangegangenen Beispiele. Da jede Instanz mehrere aktive und passive Indizes haben kann muss jedoch ein zusätzlicher Header mitgeschickt werden um die gewünschte Instanz zu spezifizieren. In der Antwort zeigt das Feld openChanges die noch abzuarbeitenden Revisionen an. Ist dieser Wert 0, ist der Index jeweilige Index auf dem aktuellsten Stand.

curl -X PUT \
  https://<CUSTOMER>.makaira.io/importer/status \
  -H 'Authorization: Basic <BASIC-AUTH> \
  -H 'Content-Type: application/json' \
  -H 'X-Makaira-Instance: <INSTANCE>'