REST API v1.0 (deprecated)

Important

New API users should use the improved API v2 as v1.0 is deprecated.

Endpoint Documentation

Apteligent’s REST API is intended to be incrementally discoverable. Starting from the allYourBase endpoint, a client should be able to determine the version of the API it wants to use, then progress toward endpoint discovery, and finally, get a token and begin retrieving data.

Note

In response to user demand and in an effort to simplify reporting, all data will be returned as UTC. The App Timezone Offset will not be available in API V1.0 after January 19. This should avoid confusion and allow you to display times as you wish.

About the REST API

The Apteligent REST API allows customer and partner software to interact with Apteligent in order to retrieve Apteligent data programmatically. Here are a few examples of the kinds of questions you can answer about your app using our APIs.

  • Which version of your app has the most users? (e.g. /errorMonitoring/pie, graph=appLoads, groupBy=appVersion)
  • Which OS version crashes the most? (e.g. /errorMonitoring/pie, graph=crashPercent, groupBy=os)
  • Which of the services I have is the slowest? (e.g. /performanceManagement/pie, graph=latency, groupBy=service)
  • How heavy is my app on data usage? (e.g. /performanceManagement/pie, graph=dataIn, groupBy=appId)
  • What are your users’ favorite devices? (e.g. /errorMonitoring/pie, graph=appLoads, groupBy=device)
  • How many users are using the latest versions of the app daily? (e.g. /errorMonitoring/graph, graph=dau, duration=43200, filter=appVersion)
  • What is my crash percentage across all my apps? (e.g. /apps, attributes=crashPercent)
  • What is the latency for all cloud services across all my apps? (e.g. /apps, attributes=latency)
  • Which API endpoints have the most errors? (e.g. /performanceManagement/pie, graph=errors, groupBy=service)

Getting Started

Request Your OAuth2 Client ID

You will need a OAuth2 client ID, which you can find in the “OAuth Tokens” tab of your user settings page.

An example OAuth2 client id: 3XAAtXd3WbozO3M6zV0hVlrdk3FWWNXP

Retrieve an OAuth2 Access Token

Armed with your client ID, the next step is to obtain an access token by supplying the user’s username and password, along with the client ID, using the Resource Owner Password Credentials Grant. Complete specification of the request, along with parameter definitions and error codes, is given in section 4.3 of RFC 6749.

Note

Apteligent’s API uses OAuth 2 (RFC 6749) and is compatible with standard OAuth2 client libraries.

The access token is long-lived. Currently, the only supported grant type is password, where the client obtains the user’s Apteligent password directly from the user, and exchanges it for a token.

OAuth2 Token Request

The endpoints in this section issue a long-lived access token when presented with appropriate credentials. In general, we adhere to conventions set forth in RFC 6749, “OAuth 2.0”, section 4.3.2. Currently, the only supported grant type is “password”.

URI

POST  https://developers.crittercism.com/v1.0/token

Important

Use appropriate base URL with respect to the Data Location of your application: North America (developers.crittercism.com), Europe (developers.eu.crittercism.com).

Parameters

  • grant_type: the OAuth2 grant type, currently only “password” supported
  • username: the customer’s username (email address)
  • password: the customer’s password
  • scope: list of scopes, separated by spaces (optional)
  • duration: an integer representing the number of seconds until the token will expire (up to 31536000, equivalent to one year. Default is 2592000 (30 days)) (optional)

Example

Requesting a token with client id WV3v7ZTaYmqtUOMNvO7oPhLi8RN9zFoo, for david@crittercism.com:
$ curl -X POST https://developers.crittercism.com/v1.0/token -u WV3v7ZTbYmqtUOMNvO7oPhLi8RN9zFoo -d 'grant_type=password&username=david@crittercism.com&password=riTiBw28%3DpmFu'

Enter host password for user 's0t2cID5Q1pkdkOi564Uoz7wo3Y6gq1l':

* Server auth using Basic with user 'WV3v7ZTaYmqtUOMNvO7oPhLi8RN9zFoo'
> POST /v1.0/token HTTP/1.1
> Authorization: Basic V1YzdjdaVGFZbXF0VU9NTnZPN29QaExpOFJOOXpGb286
> User-Agent: curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8y zlib/1.2.5
> Host: developers.crittercism.com
> Accept: */*
> Content-Length: 86
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 200 OK
< Server: gunicorn/0.14.3
< Date: Thu, 06 Feb 2014 18:39:48 GMT
< Connection: close
< Cache-Control: no-cache
< Pragma: no-cache
< Rate-Limit-Limit: 20
< Rate-Limit-Remaining: 18
< Rate-Limit-Reset: 46
< Content-Type: application/json;charset=UTF-8
< Content-Length: 99
<
{"access_token": "7oHh1moGJKysza691pa5Ucl4vgr59hGq", "token_type": "bearer", "expires_in": 2592000}

Note

Curl may prompt for a password. This should be left empty, it is an artifact of the way curl handles -u.

Important

Use appropriate base URL with respect to the Data Location of your application: North America (developers.crittercism.com), Europe (developers.eu.crittercism.com).

Rate Limiting

The API enforces limits on the number of query requests.

Limits are specified by controlling how many requests are made, by a single OAuth2 client, within a period of time called a “time bucket”. Endpoints return rate-limiting information in their HTTP headers:

Setting Description
Rate-Limit-Limit Client’s limit (calls/minute).
Rate-Limit-Remaining Average request speed (calls/minute) the client could make until the end of the current bucket, without encountering rate-limiting.
Rate-Limit-Reset Number of seconds remaining in the current bucket.

Here is an example.

$ curl -X GET -H 'Authorization: Bearer 7oHh1moGJKysza691pa5Ucl4vgr59hGq' https://developers.crittercism.com/v1.0/apps?attributes=appName,latestVersionString,mau,rating -v -v


[...]

< HTTP/1.1 200 OK

< Rate-Limit-Limit: 20

< Rate-Limit-Remaining: 18

< Rate-Limit-Reset: 46

Important

Use appropriate base URL with respect to the Data Location of your application: North America (developers.crittercism.com), Europe (developers.eu.crittercism.com).

This indicates that the client is rate limited to 20 calls per minute, averaged over the length of a time bucket. It could continue to average 18 calls per minute for the remainder of the time bucket, and the time bucket will reset in 46 seconds.

If a client exceeds its limit, it will receive an error packet describing the limits:

$ curl -X GET -H 'Authorization: Bearer 7oHh1moGJKysza691pa5Ucl4vgr59hGq' https://developers.crittercism.com/v1.0/apps?attributes=appName,latestVersionString,mau,rating -v -v

[...]

< HTTP/1.1 429 Too Many Requests [...]

{"actual": 25, "message": "API rate limit exceeded", "limit": 20, "reset": 42, "success": 0}

Important

Use appropriate base URL with respect to the Data Location of your application: North America (developers.crittercism.com), Europe (developers.eu.crittercism.com).

In this case, limit corresponds to the Rate-Limit-Limit header, reset corresponds to the Rate-Limit-Reset header, and actual is the number of calls per minute that the client has made.

Generating an API Token

Note

If you would like to obtain an API token to use the API, please go to the “OAuth Tokens” tab in your user settings page.