Skip to content
Embabel Worlds

Is this step already satisfied?

POST
/api/v1/tours/{id}/steps/{index}/status
curl --request POST \
  --url http://localhost:11044/api/v1/tours/example/steps/1/status \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "params": { "additionalProperty": "example" } }'

Answered WHEN THE STEP IS REACHED, not when the tour is fetched: a tour changes the world as it walks through it, so a verdict computed at load time describes a world that no longer exists. UNKNOWN means the step’s own query could not be answered — detail says why — and a client should run the step anyway. Repeating a step is visible and recoverable; silently skipping one is neither. A POST rather than a GET because the tour’s collected parameters are the body: the condition worth writing is usually about the thing the user just named, and without them the only expressible preconditions are those that depend on no answer.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

The tour’s id as listed by GET /tours, or the declaredId its file gave it; an unknown tour answers UNKNOWN with the reason in detail, not a 404

index
required
integer format: int32

Zero-based position of the step within the tour; an index out of range answers UNKNOWN with the reason in detail

Query Parameters

Section titled “Query Parameters”
username
string

Username to act as, whose world holds the tours; when it resolves to a user it is used in preference to the authenticated principal. Omitted or blank, the authenticated principal acts; 401 when neither resolves

Request Body

Section titled “Request Body”

The answers the tour has collected so far, as params, bound as query parameters into the step’s when and doneWhen conditions; may be omitted, which binds nothing

Media typeapplication/json

The parameters a tour has collected so far, bound into the step’s precondition

object
params
required

Values the tour has collected so far, by name, bound as query parameters of the step’s precondition

object
key
additional properties

Example generated

{
  "params": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

DONE, TODO or UNKNOWN

Media typeapplication/json

Whether a step’s precondition is already satisfied

object
detail

Why, when the status is UNKNOWN — the query error in the author’s words

string
status
required

DONE when the step’s precondition returned a row, or when its when condition returned none (the step does not apply here); TODO when it is not yet satisfied or has no precondition; UNKNOWN when its query could not be run or the tour or step does not exist, in which case the client should run the step anyway

string
Allowed values: DONE TODO UNKNOWN

Example 

{
  "status": "DONE"
}

401

Section titled “401”

Basic-auth challenge failed