Skip to main content

REST Interface

How to configure your automated tests to obtain test data via REST.

Flow​

To obtain a test dataset two calls are required:

  • POST /1/datasets - to request a dataset
  • GET /1/datasets/{datasetId}?waitUntil={deadline} - to get the dataset including the result

The first call is synchronous and returns immediately with a dataset id. The dataset status is "ACCEPTED". The second call is synchronous and returns with the dataset once it is ready or when the deadline is reached. In case the deadline is reached and the dataset is not in its final state, the call can be repeated.

The reason of this setup is to allow requesting all required data at the test suite start and then to pick each dataset just-in-time. This allows to generate test data that would not yet be available at the time of the test suite start while minimizing the time of the test suite execution.

Request and Response​

Request body​

The request body when doing a POST request for a new dataset has the following structure:

{
  "environment": "STAGE",
  "supplier": "CRM",
  "item": "customer",
  "input": {
    "country": "DE",
    "language": "de",
    "currency": "EUR"
  }
}
  • environment - the environment name where the dataset is requested
  • supplier - the supplier name of the dataset
  • item - the item name of the dataset
  • input - the input parameters of the dataset, can be an arbitrary JSON object

When doing a GET request for a dataset, the query parameter waitUntil is optional and can be used to specify a deadline as epoch milliseconds. If the dataset is not ready at the time of the request, the call will block until the deadline is reached. It is recommended to not specify a deadline too far in the future because a TCP connection needs to be kept open until the dataset is ready. On Sixpack side we guarantee 30s timeout in normal cases but unless there is an upgrade going on, a 5 minutes waiting time is still acceptable. Our experience shows that above 55s it's rather risky, and you might hit timeouts of various network elements on the route between your test and Sixpack.

Response body​

The response body has the following structure:

{
  "id": "123456",
  "status": "ACCEPTED",
  "progress": "Waiting on validation",
  "environment": "STAGE",
  "supplier": "CRM",
  "item": "customer",
  "input": {
    "country": "DE",
    "language": "de",
    "currency": "EUR"
  },
  "output": {
    "username": "testuser"
  },
  "requestDate": "2021-01-01T00:00:00Z",
  "generationDate": "2021-01-01T00:00:00Z",
  "allocationDate": "2021-01-01T00:00:00Z"
}
  • id - the dataset id
  • status - the dataset status - initially will be "ACCEPTED"
  • progress - the dataset progress - is only relevant in case the generator uses iterations and provides an intermediary status
  • (...)
  • output - the output parameters of the dataset, is the JSON representation of the return object of the generator's generate method
  • requestDate - the date when the dataset was requested
  • generationDate - the date when the dataset was generated, can be before the request date
  • allocationDate - the date when the dataset was allocated to the requester

Authentication​

Authentication requires several headers to be passed with each request including a HMAC signature. The HMAC signature is a HMAC-SHA256 signature of the concatenation: timestamp + '|' + nonce. Headers to be passed are:

  • SX-Account - The name of the account
  • SX-User - The id of the service user
  • SX-Timestamp - The unix epoch time in seconds
  • SX-Nonce - A random string to not be repeated across requests for some time

For example the headers will look like follows:

GET             https://api.sixpack.dev/1/datasets/my-dataset-id?waitUntil=123456
SX-Account      MyAccount
SX-User         208aad58-d812-4e4e-ac84-22f529a24117
SX-Timestamp:   1727815948  
SX-Nonce:       random-string-123
SX-Signature:   fcfaffa7fef86515c7beb6b62d779fa4ccf092f2e61c164376054271252821ff

The signature is calculated as HMAC265 of 1727815948|random-string-123 in hex format using your api key as the secret.

Following example shows how to construct a bash function that signs and sends a GET request:

callsixpack() {
  # Arguments: method, url, account, user, api_key
  local method=$1
  local url=$2
  local account=$3
  local user=$4
  local api_key=$5
  # Generate a random nonce
  local nonce=$(openssl rand -hex 12)
  # Get current time
  local timestamp=$(date +%s)
  # Construct the data to be signed
  local data="${timestamp}|${nonce}"
  # Calculate HMAC-SHA256 signature
  local signature=$(echo -n "$data" | openssl dgst -sha256 -hmac "$api_key" -hex | cut -d " " -f2)
  # Send request with curl
  curl -X "$method" "$url" \
    -H "SX-Account: $account" \
    -H "SX-User: $user" \
    -H "SX-Timestamp: $timestamp" \
    -H "SX-Nonce: $nonce" \
    -H "SX-Signature: $signature"
}

# Example usage:
callsixpack "GET" "https://api.sixpack.dev/1/datasets/my-dataset-id?waitUntil=123456" "MyAccount" "208aad58-d812-4e4e-ac84-22f529a24117" "YOUR_API_KEY"