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:

  1. Launch the server
  2. 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

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

POST /executions/{exec_id}/run

Parameters

Name Position Description Type
X-Fields header An optional fields mask string
exec_id path string

GET /executions/{exec_id}

Parameters

Name Position Description Type
X-Fields header An optional fields mask string
exec_id path string

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

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

providers

GET /providers/

Parameters

Name Position Description Type
X-Fields header An optional fields mask string