README
This document describes the make up of the Flood API.

Schema

The Flood API follows the Hypertext Application Language serialization format for responses, and accepts a standard ActiveModel style request body format for JSON requests, and form-data based requests for application/multipart.

Current Version

The current version of the API is v2, which is also accepted as the default version. We encourage you to explicitly specify the correct version:
1
Accept: application/vnd.flood.v2+json
Copied!

Making requests

The Flood API server is https://api.flood.io, you must use HTTPS for requests or your client will be redirected to the HTTPS version.

HTTP Verbs

Where possible, Flood API strives to use appropriate HTTP verbs for each action.
Verb
Description
HEAD
Can be issued against any resource to get just the HTTP header info.
GET
Used for retrieving resources.
POST
Used for creating resources.
PUT
Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero.
DELETE
Used for deleting resources. Will return a 204 with an empty body on success.

Authentication

Flood API supports multiple authentication strategies, depending on how you're using the API.

Basic Token

The simplest way to authenticate is by using your API token, which can be found on your account page. Example:
1
curl "https://api.flood.io/api/floods" -u "<USER_TOKEN_HERE>:"
Copied!

OAuth 2

We also support OAuth2, which allows you to generate user tokens, or register an application to develop against and allow your own users to authenticate with their account. This is ideal if you're developing an application for release as a desktop or mobile app.
This feature is still in private beta, if you would like to request access, please email [email protected]

End to End Example

Using your favourite CI build automation tool, you could execute a similar script as follows to launch and run flood tests:
1
#!/bin/bash
2
set -e
3
4
# Check we have the jq binary to make parsing JSON responses a bit easier
5
command -v jq >/dev/null 2>&1 || \
6
{ echo >&2 "Please install http://stedolan.github.io/jq/download/ Aborting."; exit 1; }
7
8
# Start a flood
9
echo
10
echo "[$(date +%FT%T)+00:00] Starting flood"
11
flood_uuid=$(curl -u flood_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx: -X POST https://api.flood.io/floods \
12
-F "flood[tool]=jmeter" \
13
-F "flood[threads]=5" \
14
-F "flood[project]=Default" \
15
-F "flood[privacy]=public" \
16
-F "flood[name]=CI Shakeout" \
17
-F "flood_files[][email protected]" \
18
-F "flood_files[][email protected]" \
19
-F "flood[grids][][infrastructure]=demand" \
20
-F "flood[grids][][instance_quantity]=1" \
21
-F "flood[grids][][region]=us-west-2" \
22
-F "flood[grids][][instance_type]=m5.xlarge" \
23
-F "flood[grids][][stop_after]=15" | jq -r ".uuid")
24
25
# Wait for flood to finish
26
echo "[$(date +%FT%T)+00:00] Waiting for flood $flood_uuid"
27
while [ $(curl --silent --user $FLOOD_API_TOKEN: https://api.flood.io/floods/$flood_uuid | \
28
jq -r '.status == "finished"') = "false" ]; do
29
echo -n "."
30
sleep 3
31
done
32
33
# Get the summary report
34
flood_report=$(curl --silent --user $FLOOD_API_TOKEN: https://api.flood.io/floods/$flood_uuid/report | \
35
jq -r ".summary")
36
37
echo
38
echo "[$(date +%FT%T)+00:00] Detailed results at https://flood.io/$flood_uuid"
39
echo "$flood_report"
40
41
# Optionally store the CSV results
42
echo
43
echo "[$(date +%FT%T)+00:00] Storing CSV results at results.csv"
44
curl --silent --user $FLOOD_API_TOKEN: https://api.flood.io/floods/$flood_uuid/result.csv > result.csv
Copied!
Last modified 1yr ago