Postman & Makaira-API

Create signed requests with Postman

Task

Check communication between Makaira API and store.

Solution

With Postman it is possible to check the requests signed with the shared secret between the store and Makaira API.

This is done by sending a POST request to the endpoint provided by the store, e.g. <shopurl>?cl=makaira_connect_endpoint in the Oxid Shop

It is recommended to create an environment configuration with the following variables

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

The following headers are required

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

With a pre-request script the hash is generated based on the current 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);

Example: Body for checking the update data

POST <shopurl>?cl=makaira_connect_endpoint
{
"action":"getUpdates","since":0,"count":10,"language":"de"}

Signing of API requests in the store

Task

Send requests directly to the Makaira API without using the Connect module.

Solution

Communication with the API is secured via signed requests. The signature is formed as a hash over the request body and a randomly generated nonce using a shared secret. The X-Makaira-Nonce and X-Makaira-Hash headers must be transmitted with the request.

PHP example for generating the headers
<?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;
}

Control of ES indices via the Makaira API

Task

Change or delete ElasticSearch indexes via the Makaira API.

Solution

Makaira allows manipulating ElasticSearch indexes via the provided API.

The <makaira-url>/indices route is provided as the endpoint.

The requests to interact with the API require a Basic-Auth header from the login credentials for the Makaira instance for verification.

To identify the relevant index, its alias - found in Makaira under "Index Configuration" - can be used, e.g. stage_passive_en

Delete an index

Note: When deleting, only passive indexes should be deleted. The importer ensures that these are automatically created again.

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

Activate a passive index

Note: Activating a passive index always switches the currently active index of the selected language to inactive.

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

Status (revision) of an index

The request to query the index status has basically the same structure as the previous examples. However, since each instance can have multiple active and passive indexes, an additional header must be sent to specify the desired instance. In the response, the openChanges field indicates the revisions still to be processed. If this value is 0, the respective index is up to date.

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