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