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/
Error
Unable to process URL: file://{{currentDir}}/swagger-api.json. Please check that the URL is a valid Swagger api-docs URL and it is accesible