Logo

REST API Documentation

All API calls begin with http://api.cloudymetrics.com/api/ or http://api.cloudymetrics.com/html/. The metrics returned are identical; the use of /api/ requests a JSON response, while /html/ requests the same JSON but converts it to HTML for the response. The HTML version is a sortable table representation of the JSON.

The API provides access to resources in three categories: providers and their properties, instances and their properties, and metrics. (The /iaas/{p}/instances/search resource searches both instance properties and metrics.)

Though this API is free, if you expect to produce a large volume of requests, please contact us.

List providers and properties

Resource Description
/iaasLists all known Infrastructure-as-a-Service providers.
Response:
  • name: the short name used in this application (e.g. amazon).
  • display_name: a prettified name (e.g. Amazon EC2).
Examples:
/iaas/{provider}
/iaas/all
Lists the properties of the named IaaS provider. The keyword all can be used in place of the provider name to report the properties of all known providers.)
Response:
  • provider: the name of the provider.
  • billing_time: the smallest increment of time billed. (prices are reported by hour regardless of this value). e.g. hourly
  • cpu_bursting: boolean value (0/1) indicating whether the CPU has a hard cap (0) or can burst if the resources are available (1).
  • bandwidth_[in/out]_price: the price in dollars of the first 2TB of bandwidth in/out.
  • bandwidth_price_scales: a boolean value (0/1) indicating whether the price of bandwidth changes some time after the 2TB mark.
Examples:


List and Search instances

Resource Description
/iaas/{provider}/instances
/iaas/all/instances
Lists all instances of the given provider (or all known instances). Warning: this list can be quite long.
Response:
  • provider: the name of the provider.
  • name: the unique name of the instance used internally.
  • display_name: the display name of the instance (usually the one used by the provider internally).
  • cpu_name: the name of the processor used in this instance. Note that not all instances have full access to the CPU (typically, the Processor Brand String from the cpuid command).
  • cpu_clock: the clock frequency of the processor as reported, typically in GHz. Note this won't always match the brand string due to the virtualization.
  • cpu_cores: the number of cores available.
  • cpu_proportion: when available, the proportion of the core guaranteed to be available to this instance. Note that a value of 1 is the default; a non-1 value is accurate, while a 1 is not necessarily accurate.
  • memory: the amount of memory available (in MB).
  • local_storage: the amount of local disk available (in GB).
  • price: the cost of this instance in dollars per hour.
Examples:
/iaas/{p}/instances/{name}
/iaas/all/instances/{name}
List an instance by name; returns the properties of an instance by name; the name entered is wildcarded.
Response: The properties of the instances.
Examples:
/iaas/{p}/instances/search/listLists the valid fields that can be searched. {p} can be any text; provider does not matter.
Response:
  • field: the fields that can be searched.
Examples:
/iaas/{p}/instances/searchSearch all of the instances of the given provider {p} (or 'all').
Parameters: A set of [field] [operator] [value] triples, joined by &. Fields may be repeated to create ranges. For example, price>.10&price<.50. The query string should be appropriately url encoded.
  • field: Any metric name or instance property; valid options can be listed using /iaas/{p}/instances/search/list.
  • operator: Any of ~, =, ==, <, <=, >, >=. If the field is non-numeric, only =, ==, and ~ may be used. ~ is an "approximately" operator.
  • value: The desired value of the field. Must be numeric for numeric fields. If the ~ operator is used, wildcards may be used in the value (* or %). Note the % must be encoded as %25.
Response: A list of instances and their properties, or HTTP status code 400 and an appropriate error message.
Examples:


List and Submit metrics

Resource Description
/iaas/{p}/instances/{name}/metrics
/iaas/all/instances/{name}/metrics
Lists all available benchmarks for the named instance. {name} is wildcarded; the metrics for any instance matching *name* will be reported.
Parameter:
(optional)
By default, all metrics are shown. Setting the 'show' parameter with a comma-separated list of valid fields will limit the results to those fields. The query string should be appropriately url encoded.
  • show:A comma-separated list of metric names to show. Using an invalid metric name will produce an HTTP 400 (Bad Request) error.
Response:
  • provider: the name of the provider.
  • name: the unique name of the instance used internally.
  • recorded: the date and time this set of metrics was recorded.
  • ping_time: the time required to ping www.google.com (averaged over 10 attempts, with the DNS lookup already cached).
  • local_read: the speed (in MB/s) of reading local instance storage; calculated using hdparm non-buffered reads, averaged over three tests.
  • remote_read: the speed (in MB/s) of reading remote storage (like Amazon EBS) where applicable; calculated using hdparm non-buffered reads, averaged over three tests.
  • local_write: the speed of writing to local instance storage, calculated by writing 1 GB to a file using dd from /dev/zero.
  • remote_write: the speed of writing to remote storage (like Amazon EBS) where applicable, calculated by writing 1 GB to a file using dd from /dev/zero.
  • dl_speed: the download speed (in MB/s not Mbps), calculated by downloading a 512MB file from a fixed location.
  • cpu_bench_blowfish, cpu_bench_cryptohash, cpu_bench_fibonacci, cpu_bench_n-queens, cpu_bench_fft, cpu_bench_raytracing: A set of (fairly) standard CPU benchmarks as implemented by hardinfo tool. Smaller is better, except for cryptohash.
  • startup_time: how long it takes from requesting this instance to being able to access it via SSH.
Examples:
/iaas/{p}/instances/{name}/metrics/{metric}
/iaas/all/instances/{name}
If only one metric name is required, this is a shortcut for the show parameter of /iaas/{p}/instances/{name}/metrics/.
Response: The given {metric} for all matching instances, from all recorded benchmarks..
  • provider: the name of the provider.
  • name: the unique name of the instance used internally.
  • recorded: the date and time this set of metrics was recorded.
  • {metric}: See metric names for the meaning of each field.
Examples:
POST /submit/metricsThis is the only available POST method; it allows remote users to submit their own metrics & benchmarks in JSON format for review and addition to the database. See contribution instructions.
Parameters: A JSON-encoded array of key-value pairs, representing recorded metrics. Any valid metric name or instance property may be included, in addition to the following special parameters:
  • instance_name: The name of the instance, preferably in the unique name used by this API.
  • auth_code: A special key provided to trusted metrics submitted that expedites additions to the database.
Response: A printed depiction of the JSON object submitted is returned along with the appropriate HTTP status code.
Examples: In pseudocode (vaguely like PHP):
$metrics = array(
    [instance_name] => m1.small
    [ping_time] => 13.468
    [dl_speed] => 36.571
    [cpu_text] => Intel(R) Xeon(R) CPU E5645 @ 2.40GHz
    [cpu_cores] => 1
    [memory] => 1761
    [cpu_clock] => 2.00007
    [cpu_bench_blowfish] => 32.744
    [cpu_bench_cryptohash] => 41.685
    [cpu_bench_fibonacci] => 7.054
    [cpu_bench_n-queens] => 23.988
    [cpu_bench_fft] => 16.122
    [cpu_bench_raytracing] => 17.106
);
$data_string = json_encode($metrics);
 
$ch = curl_init('http://api.cloudymetrics.com/api/submit/metrics');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data_string))
);

$result = curl_exec($ch);