curl (shell)

A bash script that uses the API with curl, and jq to make and read the JSON. It lists a template's labelled variables, measures the drawing it makes with the values given, and exports it as a PDF.

Download it: box.sh.

#!/usr/bin/env bash
# box.sh: list a template's inputs, measure it and export it as a PDF with the PiQ SaaS API.
# bash, curl and jq.
set -euo pipefail

: "${PIQ_API_KEY:?Set PIQ_API_KEY to your API key.}"
base="${PIQ_URL:-https://saas.parametriq.co.uk}"
base="${base%/}"
storage="${PIQ_STORAGE:-}" # optional: a registered storage's name

TEMPLATE='L=400,"Length"
W=300,"Width"
P1=[L,0]
P2=[L,W]
P3=[0,W]
POLYLINE @1,[P0,P1,P2,P3],TRUE,0'
# the template itself, or (optional) where it is kept in your storage
if [ -n "$storage" ]; then
  template=$(jq -n --arg s "$storage" '{source: {storage: $s, key: "templates/box.piq"}}')
else
  template=$(jq -n --arg t "$TEMPLATE" '{template: $t}')
fi
request=$(jq '. + {values: {L: 500, W: 250}}' <<<"$template")
trap 'rm -f inputs.json measure.json saved.json headers.txt' EXIT

# post PATH BODY OUTPUT: posts the JSON body, the response to the file OUTPUT, its headers to headers.txt
post() {
  local status
  status=$(curl -sS -o "$3" -D headers.txt -w '%{http_code}' -X POST "$base$1" \
    -H "X-API-KEY: $PIQ_API_KEY" -H 'Content-Type: application/json' --data-binary "$2")
  if [ "$status" -ge 300 ]; then
    echo "Error $status" >&2
    if [ -s "$3" ]; then # a 401 has no body
      jq -r '.title // empty, .detail // empty,
        (.errors // {} | to_entries[] | "  \(.key): \(.value | join(" "))")' "$3" >&2 || cat "$3" >&2
    fi
    rm -f "$3"
    exit 1
  fi
}

# 1. The template's labelled variables
post /inputs "$template" inputs.json
jq -r '.inputs[] | "\(.name): \(.label) (\(.kind), \(.value))"' inputs.json

# 2. The drawing measured, with the values given
post /measure "$request" measure.json
jq -r '"Size: \(.width) x \(.height), cut length: \(.layers | map(select(.layer == "Cut").length) | add // 0)"' measure.json

# 3. The drawing as a PDF
post /export/pdf "$request" box.pdf
warnings=$(grep -i '^x-piq-warnings:' headers.txt | cut -d' ' -f2 | tr -d '\r')
echo "Saved box.pdf ($warnings warnings)"

# 4. Optional: the PDF saved to your storage instead of downloaded
if [ -n "$storage" ]; then
  body=$(jq --arg s "$storage" '. + {destination: {storage: $s, key: "drawings/box.pdf"}, overwrite: true}' <<<"$request")
  post /save/pdf "$body" saved.json
  jq -r '"Saved \(.key) to \(.storage) (\(.size) bytes)"' saved.json
fi

How it works

Settings. The key comes from PIQ_API_KEY, the address from PIQ_URL (the service itself if not set) and, optionally, a storage's name from PIQ_STORAGE. Without a key the script stops at once. set -euo pipefail stops it at the first command that fails.
The template. jq -n --arg makes the JSON, so the template's quotes and new lines are escaped as they should be: the template's text as template or, when PIQ_STORAGE is set, where it is kept in your storage as source. request adds the values to it. The files the script reads answers from are removed when it ends (trap … EXIT).
post sends a body to an operation, with the key in the X-API-KEY header. curl writes the response to a file, its headers to headers.txt, and prints only the status (-w '%{http_code}').
Errors. A response that isn't a success has its status printed, then its problem description, picked out with jq: its title, its detail, and each entry of errors, the field and what is wrong with it. A 401 has no body (-s tests for an empty file), so there is nothing more to print; a body that isn't JSON is printed as it is. The file is removed, and the script exits with 1.
Inputs. POST /inputs needs only the template. Each of its inputs has a name, label, kind and value.
Measure. POST /measure with the values gives the drawing's width and height, and its lines' lengths by layer in layers; the cut length is the length on the Cut layer.
Export. POST /export/pdf answers with the PDF itself, which curl writes straight to box.pdf. The X-PiQ-Warnings header, found in headers.txt, says how many things couldn't be exported as they are.
Save (optional). With a storage, POST /save/pdf exports the same drawing and saves it to your storage at destination, overwrite: true replacing a file already there. It answers with where it saved it and its size.

A single request needs no script. This exports the drawing as a PDF:

curl -sS -X POST https://saas.parametriq.co.uk/export/pdf \
  -H "X-API-KEY: $PIQ_API_KEY" -H 'Content-Type: application/json' \
  -d '{"template":"L=400,\"Length\"\nW=300,\"Width\"\nP1=[L,0]\nP2=[L,W]\nP3=[0,W]\nPOLYLINE @1,[P0,P1,P2,P3],TRUE,0","values":{"L":500,"W":250}}' \
  -o box.pdf

Running it

Save the script as box.sh. It needs bash, curl and jq (on Debian and Ubuntu, apt install jq; on macOS, brew install jq). Then:

chmod +x box.sh
export PIQ_API_KEY=XXXX-XXXX-XXXX-XXXXX
./box.sh

It prints the template's labelled variables, the drawing's size and cut length, and saves box.pdf:

L: Length (Number, 400)
W: Width (Number, 300)
D: Depth (Number, 300)
Size: 500 x 250, cut length: 1500
Saved box.pdf (0 warnings)

With a value the template can't use ("L": "long", say), it prints the problem and stops:

Error 400
One or more validation errors occurred.
Some of the values given can't be used.
  L: L is a number.

With a key that isn't right it prints only Error 401: a 401 has no problem description.

To try the storage part, register a storage (see Register a storage), put a template in it as templates/box.piq, and set PIQ_STORAGE to the storage's name. The template is then read from your storage, and the PDF is also saved to it as drawings/box.pdf, replacing any file already there.