API Overview
Internally, Angelfish uses a RESTful API for all data requests. Externally, 3rd party applications and scripts can request data from the same API.
Requests from 3rd party applications & scripts must contain 3 components:
- the data parameters
- a valid username
- a signature
This article provides details for creating the data parameters and signature, and combining both into an API request.
Data Parameters
REQUIRED PARAMETERS
ids
The Profile ID to use for the data query - you can view a profile's ID in the summary tab of the Profile's settings. The Profile ID must exist and username used in the request must be able to access the Profile.
start-time
Accepts a date in YYYYMMDD format. Will use the timezone offset specified in the Profile's settings.
end-time
Accepts a date in YYYYMMDD format. Will use the timezone offset specified in the Profile's settings.
username
This is the username used to authenticate to Angelfish. The username must be able to access the Profile ID referenced in the ids parameter.
OPTIONAL PARAMETERS
dimensions
Passed as a comma-separated list. See the API Field Reference: Dimensions article for a list of valid dimensions.
metrics
Passed as a comma-separated list. See the API Field Reference: Metrics article for a list of valid metrics.
format
May be one of the following values.
- json: JSON format - this is the default value if format is not specified
- xml: XML format
- csv: Comma-separated format
- tsv: Tab-separated format
- jsonfields: JSON format with the dimension/metric names as object keys and their values as the object values
start
The result index to start at. Must be greater than or equal to 1. Default: 1.
max-results
The maximum number of results to return, starting at start. Default: 1000.
sort
A comma-delimited list of fields to sort by, in order. Specifying a single field will sort the results by the field in ascending order. Putting a minus (-) sign in front of a field will sort the results by the field in descending order.
Example: sort by visits first, then pageviews in descending order
...&sort=visits,-pageviews&...filters
A list of fields, conditions, and condition match values for filtering the results returned. A field may only be specified once.
The field, condition expression, and value of each filter must be URL encoded.
Dimension Filter Conditions (evaluated as strings)
| Condition Expression | Description |
|---|---|
| == | Dimension value must match exactly. |
| != | Dimension value must not match the exact string. |
| =~ | Dimension value contains the specified value. |
| !~ | Dimension value does not contain the specified value. |
Metric Filter Conditions (must be numeric)
| Condition Expression | Description |
|---|---|
| == | Metric value equals |
| != | Metric value does not equal |
| > | Metric value is greater than |
| < | Metric value less than |
| >= | Metric value greater than or equal to |
| <= | Metric value less than or equal to |
Signature
The signature is an alphanumeric string, created by a hashing function and appended to the data request. A valid authentication token is required to generate the signature.
GENERATE TOKEN
The token is requested with a valid username and password from the Angelfish server, and the token is used by the hashing function.
Tokens can be re-used indefinitely but we recommend revoking the token after a single session. Alternatively, you can also define a token expiration value (in minutes) in agf.conf.
Request a New Token
Make a POST request to /api/token/request with a valid Angelfish username and password in the Body.
The data in the Body needs to begin with "data=" (no quotes) and will fail if it's not present. Here's an example of what this should look like:
POST URL: https://10.1.2.33:9000/api/token/requestBody: data={"username":"somedude","password":"itsasecret"}Token Generated Successfully
If the user credentials pass, a JSON response is returned with the username used in the request and a newly-generated token:
{"username":"somedude","token":"1234ABCDefgh"}RESPONSE ERRORS
401: Invalid Credentials
If an invalid username and/or password is provided, the API will return a 401 status code.
403: API Tokens Not Allowed
API will return a 403 status code if API tokens are not allowed for the Angelfish instance. Tokens are enabled by default, and can be disabled by the "allow_tokens" variable in agf.conf.
405: Method Not Allowed
If the username & password are passed as a query parameter instead of in the body, you'll receive a response of 405: Method Not Allowed.
GENERATE SIGNATURE
The signature is generated by passing the token and the full request (i.e. data parameters and username) through a hash function.
The following steps must be performed IN ORDER:
- Order all parameters (including username) by parameter name, ascending.
- Concatenate all name/value pairs into a single string
- Pass the string and token to the hash function
- Attach signature to POST
EXAMPLE
Consider an API request with the following details:
- start-time=20131025
- end-time=20131031
- dimensions=source
- metrics=visits
- format=tsv
- ids=1234
- username=somedude (this is the account used to login to Angelfish)
Next, add the username to the parameters and put them in ascending order:
dimensions=source
end-time=20131031format=tsvids=1234metrics=visitsstart-time=20131025username=somedudeThen add an equal sign (=) between the names and values, and oncatenate into a single string
dimensions=sourceend-time=20131031format=tsvids=1234metrics=visitsstart-time=20131025username=somedudeThe above should be a single unbroken string, i.e. no spaces or EOL characters
Pass String and Token to Hash Function
The hash function uses HMAC MD5, base 64 encoded, and returns a signature string. Below are links to hash functions written in Perl and PHP, or you can write your own in your language of choice.
From our perl example, we'd receive a signature like this:
my $hmac = Digest::HMAC_MD5->new("1234ABCDefgh");$hmac->add("dimensions=sourceend-time=20131031format=tsvids=1234metrics=visitsstart-time=20131025username=somedude");my $signature = $hmac->b64digest;
# $signature will be something like pZP3dwZlrNtc3RSmoQoH/Q==Trim all Trailing Equal Signs from Signature
If the signature contains one or more equal signs (=) at the end of the string, remove them.
Using the example above, this signature:
pZP3dwZlrNtc3RSmoQoH/Q==...should be trimmed to this:
pZP3dwZlrNtc3RSmoQoH/QAttach Signature to POST
When the signature is attached, the request data will look something like this (signature will vary):
data={"ids":"1","start-time":"20131025","end-time":"20131031","format":"tsv","dimensions":"source","metrics":"visits","username":"somedude","signature":"pZP3dwZlrNtc3RSmoQoH/Q"}Make Request
POST the request data to the /api/data handler on your Angelfish server: