HiveMQ Swarm REST API (4.6.0)

Download OpenAPI specification:Download

Introduction

The HiveMQ Swarm Commander REST API provides endpoints for the following use cases:

  • Listing all scenarios
  • Adding a scenario
  • Removing a scenario
  • Starting a scenario
  • Stopping a scenario

API style

The Commanders's API is organized in a RESTful fashion.

The API has predictable resource-oriented URLs that consume and return JSON with the content-type application/json. It uses standard HTTP response codes and verbs. All transfered scenarios are encoded with Base64.

The base URL is the Host and configured port of your HiveMQ Swarm Commander.

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. Codes in the 2xx range generally indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error on the server side.

For all user errors a JSON response with additional details is returned in the format Problem JSON.

OpenAPI

The HiveMQ Swarm Commander REST API provides an OpenAPI 3.0 schema definition that can be imported into popular API tooling (e.g. Postman) or can be used to generate client-code for multiple programming languages.

Commander

Commander status

Commander status.

This endpoint returns the current status of the commander.

Responses

200

Success

Response Schema: application/json
commander-status
string
run-id
string
get/commander
/commander

Response samples

Content type
application/json

Return commander status

Copy
Expand all Collapse all
{
  • "commander-status": "READY",
  • "run-id": null
}

Runs

List all runs.

List all runs

This endpoint returns a list of all runs.

Responses

200

Success

Response Schema: application/json
scenarios
Array of objects (ListScenarioResponseEntry)
Array
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
get/runs
/runs

Response samples

Content type
application/json

success

Copy
Expand all Collapse all
{
  • "runs":
    [
    • {
      }
    ]
}

Start a run.

Start a run.

This endpoint accepts runs.

Request Body schema: application/json

The scenario for the run.

scenario-id
string

Responses

200

Success

Response Schema: application/json
run-id
integer <int32>
run-status
string
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
400

Bad request

409

Can not start run.

post/runs
/runs

Request samples

Content type
application/json

The id of the scenario for the run

Copy
Expand all Collapse all
{
  • "scenario-id": "1"
}

Response samples

Content type
application/json

Start run.

Copy
Expand all Collapse all
{
  • "run-id": 1,
  • "scenario-id": 1,
  • "scenario-name": "scenario",
  • "scenario-description": null,
  • "scenario-type": "XML",
  • "run-status": "STARTING"
}

Delete a run.

Delete a run.

This endpoint deletes the run with the associated id if it exists and is not running.

path Parameters
id
required
string

Responses

204

Success

404

Not Found

409

Run in progress

delete/runs/{id}
/runs/{id}

Response samples

Content type
application/json

Delete run successful

Copy
Expand all Collapse all
null

Get a run.

Get a run.

This endpoint returns the run and the associated metadata.

path Parameters
id
required
string

Responses

200

Success

Response Schema: application/json
run-id
integer <int32>
run-status
string
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-stage
string
scenario-type
string
400

Bad request

404

Not Found

get/runs/{id}
/runs/{id}

Response samples

Content type
application/json

Get run successful

Copy
Expand all Collapse all
{
  • "run-id": 1,
  • "scenario-id": 1,
  • "scenario-name": "scenario",
  • "scenario-description": null,
  • "scenario-type": "XML",
  • "run-status": "FINISHED",
  • "scenario-stage": "Stage with id 's3' (3/3)."
}

Stop a run.

Stop a run.

This operation stops runs by setting its status to 'stopping'

path Parameters
id
required
string
Request Body schema: application/json

The new state of the run.

run-status
string

Responses

200

Success

Response Schema: application/json
run-id
integer <int32>
run-status
string
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
400

Bad request

409

Can not stop run.

patch/runs/{id}
/runs/{id}

Request samples

Content type
application/json

The new state of the run

Copy
Expand all Collapse all
{
  • "run-status": "STOPPING"
}

Response samples

Content type
application/json

Stop run.

Copy
Expand all Collapse all
{
  • "run-id": 2,
  • "scenario-id": 1,
  • "scenario-name": "scenario",
  • "scenario-description": null,
  • "scenario-type": "XML",
  • "run-status": "STOPPING"
}

Scenarios

List all scenarios.

List all scenarios

This endpoint returns a list of all scenarios.

Responses

200

Success

Response Schema: application/json
scenarios
Array of objects (ListScenarioResponseEntry)
Array
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
get/scenarios
/scenarios

Response samples

Content type
application/json

success

Copy
Expand all Collapse all
{
  • "scenarios":
    [
    • {
      }
    ]
}

Upload a scenario.

Upload a scenario.

This endpoint accepts scenarios as Base64 strings and the respective metadata.Only valid scenarios can be uploaded.

Request Body schema: application/json

The scenario to upload

scenario
string
scenario-description
string
scenario-name
string
scenario-type
string

Responses

200

Success

Response Schema: application/json
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
400

Bad request

409

Can not upload scenario

post/scenarios
/scenarios

Request samples

Content type
application/json

The scenario to upload with a name, description, type and the xml/vm content encoded as Base64 string.

Copy
Expand all Collapse all
{
  • "scenario-name": "scenario",
  • "scenario-description": "An awesome scenario",
  • "scenario-type": "XML",
  • "scenario": "BASE64=="
}

Response samples

Content type
application/json

Upload scenario

Copy
Expand all Collapse all
{
  • "scenario-id": 1,
  • "scenario-name": "scenario",
  • "scenario-description": null,
  • "scenario-type": "XML"
}

Delete a scenario.

Delete a scenario.

This endpoint deletes the scenario with the associated id.

path Parameters
id
required
string

Responses

204

Success

404

Not Found

delete/scenarios/{id}
/scenarios/{id}

Response samples

Content type
application/json

Delete scenario successful

Copy
Expand all Collapse all
null

Download a scenario.

Download a scenario.

This endpoint returns the scenario as Base64 string and the associated metadata.

path Parameters
id
required
string

Responses

200

Success

Response Schema: application/json
scenario
string
scenario-description
string
scenario-id
integer <int32>
scenario-name
string
scenario-type
string
404

Not Found

get/scenarios/{id}
/scenarios/{id}

Response samples

Content type
application/json

Download scenario successful

Copy
Expand all Collapse all
{
  • "scenario-id": 1,
  • "scenario-name": "scenario",
  • "scenario-description": null,
  • "scenario-type": "XML",
  • "scenario": "BASE64=="
}