API

Queries with a ReSTful web service API.

Authentication with API key and secret

Create an access token in your account to authenticate against our API endpoint. You must authenticate using HTTP digest access authentication. The nonce sent back to the your user agent will be valid for 300 seconds.

Discovery

The discovery API allows you to discover endpoints configured in your account.

List configurations and enabled endpoints

https://api.qloudstat.com/v13/
Request
Request
GET /v13/ HTTP/1.1
Authorization: Digest username="1v5g1p75zj7oq9jfk6o5qpdrd", realm="Qloudstat API Endpoint", nonce="MTM4Njg3MzEzNTQ1ODoyZmRhY2Q4OTFjZjEzYjdlMWQxNTYxZjUzMDNlMDRkNA==", uri="/v13/", cnonce="ZmU3YjYzNTRkZGU5ZTZlNjUyYWEwMDAzMDAwNzI5YmU=", nc=00000001, qop=auth, response="3337d0f23fd8a70cb90a8571ec823e2f"
Host: qloudstat.com
Accept: */*
Response
Response

List supported dimensions for endpoint

Request
Request
GET /v13/b31d74c7-07ae-4032-932c-0077adc8c903 HTTP/1.1
Authorization: Digest username="1v5g1p75zj7oq9jfk6o5qpdrd", realm="Qloudstat API Endpoint", nonce="MTM4Njg3MzUyNDU3NjoyOThiZGMyZmI1MTNlYzQ5MWI5Nzg5OTVmYTdkZmRkNA==", uri="/v13/b31d74c7-07ae-4032-932c-0077adc8c903", cnonce="N2I2MmRmNTYyYjY4MWE2NDUyYWEwMTg4MDAwOGQ4ZWU=", nc=00000001, qop=auth, response="5ee8a9b4d44a9c3f5156ea7bc17a994e"
Host: qloudstat.com
Response
Response

List supported metric for endpoint by dimension

Request
Request
GET /v13/b31d74c7-07ae-4032-932c-0077adc8c903/uri,statuscode HTTP/1.1
Authorization: Digest username="1v5g1p75zj7oq9jfk6o5qpdrd", realm="Qloudstat API Endpoint", nonce="MTM4Njg3MzUyNDU3NjoyOThiZGMyZmI1MTNlYzQ5MWI5Nzg5OTVmYTdkZmRkNA==", uri="/v13/b31d74c7-07ae-4032-932c-0077adc8c903", cnonce="N2I2MmRmNTYyYjY4MWE2NDUyYWEwMTg4MDAwOGQ4ZWU=", nc=00000001, qop=auth, response="5ee8a9b4d44a9c3f5156ea7bc17a994e"
Host: qloudstat.com
Response
Response

Queries

You can also lookup the API endpoint for your endpoints in the configuration list of your account or use the discovery API. The format is https://api.qloudstat.com/v13/{endpoint}/{dimensions}/{metrics}?graph={graph} All requests to the API endpoint at https://api.qloudstat.com/ must be secured with SSL and authenticated with a HTTP Digest authentication header with access tokens associated to a user login in Qloudstat.

URI path variables
  • endpoint

    Required. Referencing the endpoint in your account with a unique identifier.

  • dimensions=dimension(,?)

    Required. Refer to Dimensions for documentation.

    Drilldown

    A second dimension can be added to make a combined drilldown query. Use a comma delimiter for the parameter value such as dimension=uri,operation.

  • metrics=metric(,?)

    Required. Comma delimited metrics. Refer to Metrics for documentation.

Response Formats

You can control the output format of the response to be either JSON (JavaScript Object Notation) or in CSV (comma separated values) and TSV (tab separated values). Use the Accept HTTP header to specify the output format. Valid values are application/json text/tsv and text/csv. If not specified, the default response format is application/json.

Compression

You can request GZIP compression of the response by including the header Accept-Encoding: gzip.

Query Parameters

All request parameters must be URI encoded.

  • graph=timeline|values

    Required. Either timeline for query by time or values for query by dimension values.

  • from=yyyy-mm-dd Optional (Default=Minus 30 days)
  • to=yyyy-mm-dd Optional (Default=Today)
  • limit=1-1000 Optional (Default=100)

    Limit result set for queries by dimension values.

  • filter=dimension value(,drilldown dimension value)

    Exact match filter for the first and optionally the second dimension.

    Drilldown

    For queries with a second dimension, a filter value for the first dimension is mandatory.

  • glob=dimension value(,drilldown dimension value)

    Globbing filter for the first and optionally the second dimension. You can use * and ? glob patterns when querying for values.

  • operand=equals|notequals Optional (Default=equals)

    Operand for filter.

Drilldown

A second dimension can be added to the query to find combinations.

Example usage with cURL

curl -H "Accept: application/json" \
    --digest --user 8b7bde3e-4dd3-45ae-9f1a-b49b7e5a174e:0jg3ix3h \
    https://api.qloudstat.com/v13/1c2e9d41-b4c7-4027-82f7-9445fe5cf7fb/uri/hits,bandwidth_outbound,cost_request?graph=values\&from=2012-01-01\&to=2013-02-01

Query for dimension values

Note: Responses are not pretty printed.

Request
Request
GET /v13/1c2e9d41-b4c7-4027-82f7-9445fe5cf7fb/uri/hits,bandwidth_outbound?graph=values&resolution=day&from=2013-01-01&to=2013-02-01 HTTP/1.1
Authorization: Digest username="8b7bde3", realm="Qloudstat API Endpoint", nonce="MTM1OTkxNzgyNDYzNDoyODcyOTA2OTZkZmIyOGFjMjRjZjdlNzNmOTg2NTkzMg==", cnonce="I=", nc=00000001, qop=auth, response="ffee952"
User-Agent: curl/7.28.1
Host: qloudstat.com
Accept: application/json
Response
Response

Query for timeline

Request
Request
GET /v13/1c2e9d41-b4c7-4027-82f7-9445fe5cf7fb/uri/hits?graph=timeline&from=2013-01-01&to=2013-02-01 HTTP/1.1
Authorization: Digest username="8b7bde3e-4dd3-45ae-9f1a-b49b7e5a174e", realm="Qloudstat API Endpoint", nonce="MTM2MDA3MzczMjM0NTo2MGJkNjdhMDk4MWNhZGU0MDBkZjZmYjAwY2I1NmFiYw==", uri="/v13/1c2e9d41-b4c7-4027-82f7-9445fe5cf7fb/uri/hits?graph=timeline&from=2013-01-01&to=2013-02-01", cnonce="ICAgICAgICAgICAgICAgICAgICAgIDEzNjA0MjEzMzQ=", nc=00000001, qop=auth, response="ae421978dc31dd41fb340a9bba1288e9"
User-Agent: curl/7.28.1
Host: api.qloudstat.com:443
Accept: application/json
Response
Response

Error Responses

Error responses from the service are sent as application/json with a reason and status.

Response
Response
  • 500

    Internal server error.

  • 400

    The request is not understood. Missing or invalid parameter.

    {"reason":"Bad Request","status":400}
  • 401

    Invalid token provided in digest authentication.

    {"reason":"Username 18b7bde3e-4dd3-45ae-9f1a-b49b7e5a174e not found","status":401}
  • 404

    Configuration or endpoint not found.

    {"reason":"Not Found","status":404}
  • 406

    Not acceptable. Invalid content type requested in Accept header.

    {"reason":"Not Found","status":404}