Workflow External API v.1

URL:

  • Production: https://workflow.d2s.hefest.eu/api/v1/[LAB ID]

HTTP verb: POST with JSON body.
Required HTTP headers: Content-Type and Accept (application/json).
Common request data fields:

  • “op” – operation
  • “secret” – API secret

Put order

Fields:

  • “op”: “put-order”
  • “type”: “models-by-widget”
  • “order”: arbitrary order reference ID (defined by client)
  • “user”: JSON object with field “email”
  • “confirm?”: true (boolean)
  • “units”: JSON array of units, where each unit is a JSON object with 2 fields:
    • “base”: string, base ID – the value of attribute “data-unit” of the widget (which is technically ID of base unit of the widget)
    • “payload”: JSON array where each items is a JSON object with 2 fields:
      • “slot”: string, model slot name, which can be found Demo Widget form.
      • “image”: string, URL of image to download and print on the slot.

Example:

{
"op":       "put-order",
"type":     "models-by-widget",
"secret":   "Yay-yShn-2H",
"order":    "Order #1",
"user":     {"email": "astoon.net@gmail.com"},
"confirm?": true,
"units": [
  {
        "base": "5e52e550-5964-41c8-a612-4e9df7372401",
        "payload": [
             {
               "slot": "Slot 1",
               "image": "http://example.org/image-1.jpg"
             },
             {
               "slot": "Slot 2",
               "image": "http://example.org/image-2.jpg"
             }
       ]
    }
]
}

Response

First, we download all the images to our storage. This is a synchronous operation, not a delayed one. In other words, the response takes the time required to download all the images. Then, in case of a success response, you definitely know that the images are pulled from your storage and saved in our storage. Further operations (processing the images) are performing asynchronously after success response. The response should be parsed by its HTTP Status Code. We return additional information as data in response JSON body, which is useful to test, debug, handle errors.

  • Success
    • Code: 200
    • Data:
      • “message”: text message
      • “order-num”: integer, our public order num
  • Unauthorized (invalid API key)
    • Code: 401
    • Data:
      • “message”: text message
  • Invalid request data (query doesn’t conform the spec defined in this document)
    • Code: 400
    • Data:
      • “message”: text message
      • “type”: “invalid-by-spec”
      • “problems”: JSON object describing validation problems
  • Failed to download image
    • Code: 400
    • Data:
      • “message”: text message
      • “type”: “download-error”
      • “url”: which is URL of the image
  • Incorrect (e.g. non-existing) “base” ID
    • Code: 400
    • Data:
      • “message”: text message
      • “type”: “wrong-base-id”
      • “id”: wrong base id value
    • Incorrect slot name
      • Code: 400
      • Data:
        • “message”: text message
        • “type”: “slot-not-found”
  • Server error (Code: 500) means a bug on our side, please report it to us.

The client code should parse HTTP Status Code. For status code 400, when you need to parse error reason programmatically, please don’t rely on field “message” – it is a human-readable text. Instead, you can parse field “type” (possible values are “invalid-by-spec”, “download-error”, “wrong-base-id”).

Presenting