Source: https://api.octoperf.com/doc/on-premise-agent/provider-type/custom-http/

# Custom HTTP Provider

![Rest API](https://api.octoperf.com/doc/on-premise-agent/provider-type/img/restapi_apidoc.svg)

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](https://en.wikipedia.org/wiki/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](https://api.octoperf.com/doc/on-premise-agent/provider-type/on-premise/) 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](https://en.wikipedia.org/wiki/JSON) response with the following format:

```json
{
  "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. |