genroc

    docs / Reference / REST API

    Definitions

    The 5 HTTP endpoints under Definitions.

    GET /api/definitions

    List all registered process definitions (newest registered first)

    Requires the read permission (or admin).

    ParameterInDescription
    created_afterqueryOnly versions registered at/after this unix-millis timestamp
    created_beforequeryOnly versions registered strictly before this unix-millis timestamp
    sortquerySort key (per-endpoint whitelist; omit for the default)
    orderquerySort direction (omit for the endpoint default). One of asc, desc.
    limitqueryPage size (default 20, cap 100)
    afterqueryCursor from a previous page's page.next_cursor — fetch the next page
    beforequeryCursor from a previous page's page.previous_cursor — fetch the previous page

    Response

    {
      "items": null,
      "page": {
        "size": 0,
        "items_before": 0,
        "items_after": 0,
        "sort": "",
        "order": ""
      }
    }

    Fails with 400, 500.

    GET /api/definitions/{name}

    A process definition exactly as it was applied, x- keys included: the latest version, or the one version names

    Requires the read permission (or admin).

    ParameterInDescription
    versionqueryThe version to read. Omitted, the latest
    namepathThe process name

    Response

    {
      "name": "order_pipeline",
      "version": 3,
      "definition": {
        "name": "order_pipeline",
        "x-builder": {
          "zoom": 1
        },
        "tasks": [
          {
            "id": "charge",
            "switch": "end"
          }
        ]
      }
    }

    Fails with 400, 404, 500.

    PUT /api/definitions

    Apply process definitions to a channel, atomically. Content already stored is not a new version, so a repeated apply changes nothing

    Requires the deploy permission (or admin).

    Request

    {
      "definitions": [
        {
          "name": "order_pipeline",
          "tasks": [
            {
              "id": "charge",
              "action": {
                "type": "fetch",
                "url": "http://localhost:9001/charge",
                "method": "post",
                "result_schema": {
                  "type": "object",
                  "properties": {
                    "charged": {
                      "type": "boolean"
                    }
                  }
                },
                "timeout": {
                  "for": "5s"
                }
              },
              "on_error": [
                {
                  "retry": {
                    "retries": 3
                  }
                }
              ],
              "switch": [
                {
                  "case": "self.output.charged == true",
                  "goto": "$ship"
                },
                {
                  "goto": "$refund"
                }
              ]
            },
            {
              "id": "ship",
              "action": {
                "type": "fetch",
                "url": "http://localhost:9002/ship",
                "method": "post",
                "timeout": {
                  "for": "3s"
                }
              },
              "on_error": [
                {
                  "retry": {
                    "retries": 2
                  }
                }
              ],
              "switch": [
                {
                  "goto": "end"
                }
              ]
            },
            {
              "id": "refund",
              "action": {
                "type": "fetch",
                "url": "http://localhost:9003/refund",
                "method": "post",
                "timeout": {
                  "for": "3s"
                }
              },
              "on_error": [
                {
                  "retry": {
                    "retries": 1
                  }
                }
              ],
              "switch": [
                {
                  "goto": "end"
                }
              ]
            }
          ],
          "input_schema": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "integer"
              }
            },
            "required": [
              "order_id"
            ]
          }
        }
      ],
      "channel": "latest"
    }

    Response

    [
      {
        "name": "order_pipeline",
        "version": 1,
        "saved": true,
        "previous": 0,
        "same_runtime": false
      }
    ]

    Fails with 400, 500.

    POST /api/definitions/validate

    Dry-run an apply: the same request, every check, and the answer it would give, with nothing written

    Requires the read permission (or admin).

    Request

    {
      "definitions": [
        {
          "name": "order_pipeline",
          "tasks": [
            {
              "id": "charge",
              "action": {
                "type": "fetch",
                "url": "http://localhost:9001/charge",
                "method": "post"
              },
              "switch": []
            }
          ]
        }
      ],
      "channel": "latest"
    }

    Response

    [
      {
        "name": "order_pipeline",
        "version": 1,
        "saved": true,
        "previous": 0,
        "same_runtime": false
      }
    ]

    Fails with 400, 500.

    POST /api/definitions/compat

    Compare two sets of process versions: could an instance running one continue under the other, and does the newer one still honour the output contract consumers were written against. It is a shape check — it cannot see a change of meaning such as dollars becoming cents

    Requires the read permission (or admin).

    Request

    {
      "from": {
        "channel": "latest"
      },
      "to": {
        "versions": {
          "order_pipeline": 3
        }
      },
      "process": "order_pipeline"
    }

    Response

    {
      "compatible": true,
      "passes": false,
      "processes": [
        {
          "name": "order_pipeline",
          "status": "compared",
          "from": 1,
          "to": 3,
          "upgrade": {
            "compatible": true
          },
          "contract": {
            "compatible": false
          },
          "changed": [
            {
              "address": "ship:fetch.url",
              "task": "ship"
            }
          ],
          "issues": [
            {
              "member": "contract",
              "address": "output",
              "path": "fee",
              "message": "number → string",
              "gating": true
            }
          ]
        }
      ]
    }

    Fails with 400, 404, 500.