Skip to content

Custom HTTP Provider

Rest API

The remote provider is possibly the most versatile solution to automate launching OctoPerf agents / hosts on your own. The principle is simple: OctoPerf sends requests to a remote server (of your own), responsible of starting / stopping the hosts used for load generation.

Prerequisites

The remote provider requires:

  • A remote web server which is accessible from OctoPerf's backend perspective,
  • The remote web server must implement the Rest API defined subsequently.

Rest APIs

The following Rest APIs must be implemented by your web server. This web server will be contacted by OctoPerf backend when hosts running OctoPerf Agents must be started / rebooted / stopped

Response Format

All HTTP responses are expected to be of application/json; charset=utf-8 Content-type.

Response Types

HTTP Responses are expected to be either:

  • ValueWrapper<String>: refers to a json response with the following format:
{
  "value": "my-value"
}

The json value field contains the expected returned value.

  • Void: in that case, the API is simply expected to return an HTTP 200 OK response, no response body is required.

Let's explore the APIs that must be implemented

Variables

In the following Rest API documentation, variables are annotated as {myVariable}. The following variables are predefined:

  • {baseUrl} designates the URL of the remote API. Example: http://api.mycompany.com/octoperf.

Variables show which part of the API contains dynamic data (contextual to the call).

Instances API

The instances API must be implemented with the following endpoints:

Endpoint Description Expected Response
GET {baseUrl}/instances/{instanceId}/state?region={region}&zone={zone} Return given instance state. Expected states: running when the instance is up and running. HTTP 200 OK with body: { "value": "running"}
POST {baseUrl}/instances, with form urlencoded body: userData={userData}&region={region}&type={type} Create the host with given user-data (script to run on instance startup). Returns the instanceId as response. HTTP 200 OK with body: { "value": "instanceId"}
PUT {baseUrl}/instances/{instanceId} Restarts the instance with id instanceId. HTTP 200 OK
DELETE {baseUrl}/instances?instanceId={instanceId} Terminates and deletes the instance with id instanceId. HTTP 200 OK

The parameters below are explained:

  • instanceId: unique identifier of a given instance. An instance is a host running the OctoPerf Agent container. Example: i-d23efca0d. The identifier must be unique. The remote server must be capable of looking up an instance with the given instanceId,
  • region: name of the region. Example: eu-west-1, paris. Regions are configured within the provider through OctoPerf's Web UI. The region name is an hint to know where the instance is supposed to be running,
  • zone: Zone where the instance is running. Example: a, b or default. Zones are configured within the provider through OctoPerf's Web UI. The region name is an hint to know where the instance is supposed to be running,
  • type: Type of instance to run. Can be SMALL, MEDIUM, LARGE or XLARGE. The type of instance is configured within the provider through OctoPerf's Web UI. It gives an insight on the type of instance your server is supposed to launch.

Static IPs API

Static IPs (which can also be referred as Elastic IPs or Dedicated IPs) are IPs being allocated ahead of time. Those IPs can then be linked to a running instance automatically. When the instance is running, any static IP available within the same region is associated to the running instance.

Endpoint Description Expected Response
POST {baseUrl}/static-ips/allocate with body region={region}&zone={zone} Allocates a new static IP in the given region. HTTP 200 OK with body: { "value": "ipId"}
PUT {baseUrl}static-ips/associate with body region={region}&zone={zone}&instanceId={instanceId}&id={ipId} Associates the static IP with id ipId to the instance with id instanceId HTTP 200 OK with body: { "value": "associationId"}, where associationId is the id of the link between the static IP and the instance. Empty if none.
PUT {baseUrl}/static-ips/dissociate with body region={region}&zone={zone}&instanceId={instanceId}&id={ipId}&associationId={associationId} Dissociates the static IP with id ipId from instance instanceId HTTP 200 OK, no body.
DELETE {baseUrl}/static-ips/release?region={region}&zone={zone}&id={ipId} Releases the static IP. HTTP 200 OK, no body.