Entitlement Service Monitoring API entitlement-service-monitoring-api

API Overview api-overview

Entitlement Service Monitoring (ESM) is implemented as a WOLAP (Web-based Online Analytical Processing) project. ESM is a generic business-reporting Web API backed by a data warehouse. It acts as an HTTP query language that enables typical OLAP operations to be performed RESTfully.

The ESM API provides a hierarchical view of the underlying OLAP cubes. Each resource (dimension in the dimension hierarchy, mapped as a URL path segment) generates reports with (aggregated) metrics for the current selection. Each resource points to its parent resource (for roll-up) and its sub-resources (for drill-down). Slicing and dicing are achieved via query string parameters pinning dimensions to specific values or ranges.

The REST API provides the available data within a time interval specified in the request (falling back to default values if none provided), according to the dimension path, provided filters, and selected metrics. The time range will not be applied for reports that do not contain time dimensions (year, month, day, hour, minute, second).

The endpoint URL root path will return the overall aggregated metrics within a single record, along with the links to the available drill-down options. The API version is mapped as the trailing segment of the endpoint URI path. For example, https://mgmt.auth.adobe.com/*v2* means that the clients will access WOLAP version 2.

The available URL paths are discoverable via links contained in the response. Valid URL paths are held to map a path within the underlying drill-down tree that holds (pre-) aggregated metrics. A path in the form /dimension1/dimension2/dimension3 will reflect a pre-aggregation of those three dimensions (the equivalent of an SQL clause GROUP BY dimension1, dimension2, dimension3). If such a pre-aggregation does not exist and the system cannot compute it on the fly, the API will return a 404 Not Found response.

Drill-down Tree drill-down-tree

The following drill-down trees illustrate the dimensions (resources) available in ESM 2.0 for [Programmers] (#esm_dimensions) and MVPDs.

Dimensions available to Programmers progr-dimensions

Dimensions available to MVPDs mvpd-dimensions

A GET to the https://mgmt.auth.adobe.com/v2 API endpoint will return a representation containing:

Following a drill-down path (step by step):
/dimensionA/year/month/day/dimensionX retrieves the following
response:

Filters

Except for the date/time dimensions, any dimension available for the current projection (dimension path) can be filtered by using its name as a query string parameter.

The following filtering options are available:

There is also a special usage for the dimension names in the query string: If the dimension name is used as a query string parameter with no value, this will instruct the API to return a projection that includes that dimension in the report.

Example ESM Queries

The following query string parameters have reserved meanings for the API (and therefore they cannot be used as dimension names, or else no filtering would be possible for such a dimension).

ESM API Reserved Query String Parameters

The only available HTTP method currently is GET. Support for OPTIONS /
HEAD methods may be provided in future versions.

ESM API Status Codes esm-api-status-codes

Data Formats data-formats

The data is available in the following formats:

The following content negotiation strategies can be used by clients (the precedence is given by the position in the list – first things first):

Both the “extension” and the query parameter support the following values:

If no media type is specified by any of the strategies, the API will produce JSON content by default.

Hypertext Application Language hypertext-application-language

For JSON and XML, the payload will be encoded as HAL, as described here: http://stateless.co/hal_specification.html.

The actual report (a nested tag/property called “report”) will consist of the actual list of records containing all the selected/applicable dimensions and metrics with their values, encoded as follows:

JSON

 "report": [
  {
    "dimension1": "d1",
    ...
    "metric1": "m1",
    ...
  }, {
    ...
  }
]

XML

 <report>
  <record dimension1="d1" ... metric1="m1" ... />
  ...
</report

For XML and JSON formats, the order of the fields (dimensions and metrics) within a record is unspecified – but consistent (the order will be the same in all records). However, clients should not rely on any particular order of the fields within a record.

The resource link (the “self” rel in JSON and the “href” resource attribute in XML) contains the current path and the query string used for the inline report. The query string will reveal all of the implicit and explicit parameters, so that the payload will explicitly point out the time interval used, the implicit filters (if any), and so on. The rest of the links within the resource will contain all of the available segments that can be followed in order to drill down in the current data. A link for roll-up will also be provided, and it will point to the parent path (if any). The href value for the drill-down/roll-up links only contains the URL path (it does not include the query string, so this needs to be appended by the client if needed). Note that not all of the query string parameters used (or implied) by the current resource will be applicable for “roll-up” or “drill-down” links (for example, the filters may not apply to sub- or super- resources).

Example (assuming we have a single metric called clients and there is a pre-aggregation for year/month/day/...):

   <resource href="/esm/v2/year/month?start=2012-07-20T00:00:00&end=2012-08-20T14:35:21">
   <links>
   <link rel="roll-up" href="/esm/v2/year"/>
   <link rel="drill-down" href="/esm/v2/year/month/day"/>
   </links>
   <report>
   <record month="6" year="2012" clients="205"/>
   <record month="7" year="2012" clients="466"/>
   </report>
   </resource>

CSV

In the CSV data format, no links or other metadata (except for the header row) will be provided inline; instead, the selection metadata will be provided in the file name, which will follow this pattern:

    esm__<start-date>_<end-date>_<filter-values,...>.csv

The CSV will contain a header row and then the report data as subsequent rows. The header row will contain all the dimensions followed by all of the metrics. The sort order of the report data will be reflected in the order of the dimensions. Therefore, if data is sorted by D1 and then by D2, the CSV header will look like: D1, D2, ...metrics....

The order of the fields in the header row will reflect the sort-order of the table data.

Example: https://mgmt.auth.adobe.com/v2/year/month.csv will produce a file named report__2012-07-20_2012-08-20_1000.csv with the following content:

Data Freshness data-freshness

The successful HTTP responses contain a Last-Modified header which indicates the time when the report in the body was last updated. The lack of a Last-Modified header indicates that the report data is computed in real-time.

Usually, coarse-grained data will be updated less frequently than fine-grained data (e.g., by-the-minute values, or hourly values, may be more up-to-date than the daily values, especially for metrics that cannot be computed based on smaller granularities, like unique counts).

Future versions of ESM may allow clients to perform conditional GETs by providing the standard “If-Modified-Since” header.

GZIP Compression gzip-compression

Adobe strongly recommends that you enable gzip support in clients that fetch ESM reports. Doing this will greatly reduce the size of the response which in turn reduces your response time. (The compression ratio for ESM data is in the 20-30 range.)

To enable gzip compression in your client, set the Accept-Encoding: header as follows: