BrowserMob API - BETA!

version 052010

Basics

• The API is entirely HTTP based and all data is returned in JSON format
• The API is in beta and we reserve the right to tweak it in the future
• All parameters should be converted to UTF-8 and URL encoded
• You will need an API key and secret to access the API. You can find your API key here
• The examples given below utilize BrowserMob’s command line tool, which you can find here

Authentication

BrowserMob’s API uses a encrypted signature to guaranteed the security of the data being transmitted. Please note that your secret key is never sent through the wire.

All API requests must include the following parameters either in the query string (for GETs) or body (for POST):

• key - your API key
• timestamp - the current time relative to GMT in millisecond from EPOCH
• nonce - a random string that uniquely represents the request - usually a UUID
• signature - see below

Signing requests:

The signature parameter should be created using the following pseudo algorithm:

1. Sort (by parameter name with natural byte ordering) all request parameters with the exception of the signature
2. URL encode all the parameter names and value (including empty ones)
3. Separate the encoded parameters names from their values with a equal sign (=) - even if the parameter is empty
4. Join multiple parameters using &
5. Assemble a string in the format below containing all the data to be signed:

data = VERB + '\n' + HOST + '\n' + PATH + '\n' + normalized parameter string

where:

• VERB is the HTTP verb being used (either POST or GET)
• HOST is the destination hostname as sent in the HOST header. For example: browsermob.com

• PATH is the HTTP absolute path component of the URI up to, but not including, the query string. If empty, use “/”. For example: /a/m/all

• The signature will be the base64Encoding of the HMAC-SHA1 of data using your API secret.

Resources:

Monitoring API

Fetching job information

http://browsermob.com/a/m/{id}

where id is:

• the id of a monitoring job
• “all” to return a list of all jobs available along with information about their state.

Fetching precomputed metrics

BrowserMob’s API is capable of providing precomputed and rolled up metrics for all monitoring jobs. To fetch such metric you must provide the following parameters:

• metric - see below for a list of available metrics
• start - the start time, relative to GMT in milliseconds from EPOCH
• end - the end time, relative to GMT in millisecond from EPOCH
• resolution - the resolution (time period) you would like the data averaged out to (see below for a list of them)

The following metrics are available for all monitoring jobs:

• success - in essence a summary of the job, including number of failures between start and end dates
• responseTime - includes all summary data plus response time information such as min,max and average
• responeTimeWithErrors - includes everything in responseTime plus an error summary
• responseTimeForObject - similar to responseTime but for object level data instead

Available resolutions:

• hour - data is averaged out on a hourly basis
• day - data is averaged out on a daily basis
• month - data is averaged out on a monthly basis
• single - returns non rolled up information including individual transaction information

A note on resolution:

Response time data is almost solely relevant in relation to its progression over time hence we provide simple APIs to give you high level “aggregated” information. For the cases in which you would like to look at a specific transaction data, let’s say to find out which object (css, html, js, etc…) was causing the response time spike you saw on the graphs, we provide you a “single” resolution level that gives you ids for individual transactions. Armed with those ids you can fetch in-depth transaction data using the resource below.

Examples:

Querying a job for its “success” metric:

$ ./bmob.py -i -d "metric=success,start=1268496428,end=1271088428,resolution=hour" -c d86f6cfddda94fcea5b5acc86441ff30:81851c7b5 http://browsermob.com/a/m/62c6f594d70648deb17861b82775d4be { "LOCAL": [ { "errors": 57, "total": 57, "date": 1270494000000, "error": false }, [...]

Fetching transaction information:

http://browsermob.com/a/m/{id}/{transaction}

where transaction is the id of a monitoring job transaction.

Examples:

$ ./bmob.py -i -c d86f6cfddda94fcea5b5acc86441ff30:81851c7b5 http://browsermob.com/a/m/62c6f594d70648deb17861b82775d4be/98 [...]

Load Testing

Fetching a list of all load tests for an account:

http://browsermob.com/a/l/{id}

where id is:

• the id of a load test
• “all” to return a list of all load tests available along with information about their state.

Fetching information on a specific test:

$ ./bmob.py -i -c d86f6cfddda94fcea5b5acc86441ff30:81851c7b5 http://browsermob.com/a/l/1594 { "name": "asdasdasd", "failures": [ { "line number": 8, "headersUrl": null, "videoUrl": null, "screenshotUrl": null, "bodyUrl": null, "count": 1, "scriptId": "1c4e455f48814e9899b407075280a4c4", "message": "Wrapped java.lang.RuntimeException: Timed out after 10000 ms while waiting network traffic to stop" } ], "region": "US_EAST", "stats": { "failures": 1, "transactions": 45, "failureScreenshots": 1, "objects": 744 }, "end": 1271048376000, "id": 1594, "start": 1271047876000, "scriptsCount": 1, "state": "ABORTED", "accountId": 1115 }

Misc:

HTTP response codes

BrowserMob utilizes JSON and HTTP response codes to convey information back to the API consumer. Currently the following HTTP response codes are meaningful:

• 200 - success (this is always accompanied by a JSON document)
• 400 - bad request
• 401 - Invalid creds (your SECRET and KEY combination is not valid)
• 406 - Not accessible - request is understood but your account is inactive
• 413 - Request Entity Too Large - if you exceed the maximum allowed POST size
• 500 - Error - please let us know if you see this

Links:

• You can download jsonpretty (a JSON indentation tool) from here
• A amazon signature tester: (http://developer.amazonwebservices.com/connect/message.jspa?messageID=26727)