REST Server¶
Quick Start¶
This short tutorial shows how to use the API to perform a step-by-step benchmarking test.
First, we need to create a new session. This can be done making a POST
request to /api/v1/sessions
providing the provider name and service type.
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{\
"provider": "my-provider",\
"service": "my-service-type"\
}' http://localhost:5000/api/v1/sessions
Alternatively, the provider configuration can be provided directly in the request payload. For instance, a typical request to create a benchmarking session for Amazon EC2 would be:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{\
"config": {\
"provider": {\
"class": "benchsuite.stdlib.provider.libcloud.LibcloudComputeProvider",\
"name": "ec2-ggiammat",\
"driver": "ec2",\
"access_id": "<your_access_id>",\
"secret_key": "<your_key>",\
"region": "us-west-1"\
},\
"centos_micro": {\
"image": "ami-327f5352",\
"size": "t2.micro",\
"vm_user": "ec2-user",\
"platform": "centos_6",\
"key_name": "<keypair_name>",\
"ssh_private_key": "----BEGIN RSA PRIVATE KEY-----\nIIE... [...] ...6alL\n-----END RSA PRIVATE KEY-----"\
}\
}\
}' http://localhost:5000/api/v1/sessions/
Important
Providing the configuration directly in the request payload, your credentials will be sent over the network unencrypted. Do it only when the server is running in a trusted environment!
Note
The ssh private key msut be provided on a sinlge line (json does not support multiline values), but the line ends must be preserved. A convenient method to generate this string in bash is:
sed -E ':a;N;$!ba;s/\r{0,1}\n/\\n/g' my-key.pem
The response will contain the id
of the session created:
{
"id": "58920c6c-c57c-4c55-a227-0ab1919e83be",
[...]
}
Now we can create a new benchmarking test execution in the session (note that the id of the session is used in the request URL:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
"tool": "idle", \
"workload": "idle30" \
}' http://localhost:5000/api/v1/sessions/58920c6c-c57c-4c55-a227-0ab1919e83be/executions/
The response will contain (along with other execution details) the id
of the execution:
{
"id": "253d9544-b3db-11e7-8bc2-742b62857160",
[...]
}
With this execution id we can now invoke the prepare step that will create the resources on the provider, install the necessary tools and load the workloads:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' http://localhost:5000/api/v1/executions/253d9544-b3db-11e7-8bc2-742b62857160/prepare
Finally, we can invoke the run step:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' http://localhost:5000/api/v1/executions/253d9544-b3db-11e7-8bc2-742b62857160/run
The response of the prepare and run steps contain the start time and the duration of the operation:
{
"started": "2017-10-18 08:18:33",
"duration": "32.28253793716431"
}
The same session can be used to run multiple executions. At the end, the session and the resources created (e.g. VM) can be destroyed using the DELETE operation:
curl -X DELETE --header 'Accept: application/json' http://localhost:5000/api/v1/sessions/58920c6c-c57c-4c55-a227-0ab1919e83be
Swagger Doc¶
This documentation is autogenerated from the Swagger API Specification using sphinx-swaggerdoc.
A better documentation for the REST API can be found directly in the REST Server:
- Launch the server
- Open http://localhost:5000/api/v1/
sessions¶
POST /sessions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /sessions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /sessions/{session_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
session_id | path | The id of the session | string |
GET /sessions/{session_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
session_id | path | The id of the session | string |
POST /sessions/{session_id}/executions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
session_id | path | string |
GET /sessions/{session_id}/executions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
session_id | path | string |
executions¶
GET /executions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /executions/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /executions/{execution_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
execution_id | path | The id of the execution | string |
GET /executions/{execution_id}/request
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
execution_id | path | The id of the execution | string |
GET /executions/{execution_id}/runs
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
execution_id | path | The id of the execution | string |
providers¶
POST /providers/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /providers/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /providers/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /providers/{provider_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
provider_id | path | The id of the provider | string |
PUT /providers/{provider_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
PATCH /providers/{provider_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/check
Parameters
Name | Position | Description | Type |
---|---|---|---|
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/vm/flavours
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/vm/images
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/vm/params
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/vm_images
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
GET /providers/{provider_id}/vm_sizes
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
provider_id | path | The id of the provider | string |
benchmarks¶
GET /benchmarks/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /benchmarks/{benchmark_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
benchmark_id | path | string |
users¶
POST /users/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /users/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /users/{user_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
user_id | path | The id of the user | string |
PUT /users/{user_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
user_id | path | The id of the user | string |
GET /users/{user_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
user_id | path | The id of the user | string |
GET /users/{username}/scopes
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
username | path | The id of the user | string |
organizations¶
POST /organizations/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /organizations/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /organizations/{organization_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
organization_id | path | The id of the organization | string |
PUT /organizations/{organization_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
organization_id | path | The id of the organization | string |
GET /organizations/{organization_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
organization_id | path | The id of the organization | string |
POST /organizations/{organization_id}/users
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
organization_id | path | The id of the organization | string |
GET /organizations/{organization_id}/users
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
organization_id | path | The id of the organization | string |
DELETE /organizations/{organization_id}/users/{user_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
organization_id | path | The id of the organization | string |
user_id | path | string |
workloads¶
POST /workloads/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /workloads/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /workloads/download
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /workloads/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /workloads/{workload_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
workload_id | path | The id of the workload | string |
PUT /workloads/{workload_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
workload_id | path | The id of the workload | string |
GET /workloads/{workload_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
workload_id | path | The id of the workload | string |
GET /workloads/{workload_id}/download
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
workload_id | path | The id of the workload | string |
GET /workloads/{workload_id}/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
workload_id | path | The id of the workload | string |
schedules¶
POST /schedules/
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
GET /schedules/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
GET /schedules/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
DELETE /schedules/{schedule_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
schedule_id | path | The id of the schedule | string |
PUT /schedules/{schedule_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
payload | body | ||
X-Fields | header | An optional fields mask | string |
schedule_id | path | The id of the schedule | string |
GET /schedules/{schedule_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
schedule_id | path | The id of the schedule | string |
GET /schedules/{schedule_id}/user_actions
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
schedule_id | path | The id of the schedule | string |