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/
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 |
executions¶
GET /executions/{exec_id}
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
exec_id | path | string |
POST /executions/{exec_id}/run
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
exec_id | path | string |
POST /executions/{exec_id}/prepare
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
exec_id | path | string |
GET /executions/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |
default¶
sessions¶
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 |
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/
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 |
providers¶
GET /providers/
Parameters
Name | Position | Description | Type |
---|---|---|---|
X-Fields | header | An optional fields mask | string |