Reporting API

This document describes the RTI Business Intelligence API. The API exposes our Data Warehouse through REST API. As a result this enables seamless integration with clients and existing dashboards. RTI VUE is an example of the integration of the REST API to our BI data.

Please see Thor Reporting Functional Specs for groupings dimensions, and metrics definitions for additional info.

Overview

The RTI Business Intelligence API enables our customers to have direct access to important data related to their use of Kibo Solutions through an always-available REST API. This data can then be incorporated into executive dashboards or other BI tools giving key decision makers a view of the system’s performance on a regular basis. The API allows customers to choose from a list of available metrics, and specify a time period and format (CSV or JSON).

Benefits

• Direct access to the data via an open API
• Run real-time queries or store data onsite for larger, more complex reports.
• Create a script to run automatically every day, saving you time.
• Access large amounts of data – the file size is only limited by your capacity to consume it
• Baynote maintains at least 2 years of data for each of our customer instances

Framework

• We provide most reports in real-time including custom views of the BI data.
• The BI solution leverages our Big Data infrastructure including Hadoop and Hive and exposes the data via a Real Time tier of SQL Servers.
• RTI produces the data using reporting jobs that are typically run on a nightly basis and moving to a combination of real-time update and batch updates (Lambda architecture).

Structure of the REST URLs

To use a REST API, your application will make an HTTP request and parse the response.

The BI REST API uses csv, json and html as its output formats. It is a read-only API. The standard HTTP method GET is used to access reporting resources. URLs for Reporting REST API have the following structure:

http://host:port/BI/VERSION/SITE/resource-name?<parameters>

where

• SITE: CN_CC
• VERSION: 1

Security

The API leverages AAA for access leveraging Spring Security.

Sample Request to Production

production: http://prod-rpt01:8080 (e.g. http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01)

prod sample calls

http://prod-rpt01:8080/BI/1/lumber_www/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/theknot_shop/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01
http://prod-rpt01:8080/BI/1/netshoes_mx/dailytotalsmetrics?page=1&size=10

Resources

Totals

• dailytotalsmetrics
• weeklytotalsmetrics
• monthlytotalsmetrics

Attributes

• dailyattributesmetrics
• weeklyattributesmetrics
• monthlyattributesmetrics

Products

• dailyproductsmetrics
• weeklyproductsmetrics
• monthlyproductsmetrics

Recs

• dailyrecsmetrics
• weeklyrecsmetrics
• monthlyrecsmetrics

Tests

• dailytestsmetrics
• weeklytestsmetrics
• monthlytestsmetrics

Email

• dailyemailmetrics
• weeklyemailmetrics
• monthlyemailmetrics

Security

The API leverages AAA for access leveraging Spring Security.

Sample Request to Production

production: http://prod-rpt01:8080 (e.g. http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01)

prod sample calls

http://prod-rpt01:8080/BI/1/lumber_www/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/theknot_shop/dailytotalsmetrics?page=1&size=10
http://prod-rpt01:8080/BI/1/madewell_www/dailyproductsmetrics?format=html&start=2014-01-01
http://prod-rpt01:8080/BI/1/netshoes_mx/dailytotalsmetrics?page=1&size=10

Common Parameters

Filter by data

Start

Optional. Indicates beginning of the reporting range. Date/time values are expressed in ISO 8601 format. If the time falls within a period and is not at the beginning of a period, then that period is included in the returned data.

End

Optional. Indicates the end of the reporting range. Date/time values are expressed in ISO 8601 format. If this parameter is not specified, the current time is assumed. If the time is within a period, then the last partial period is not included in the returned data.

You can specify an api call without start and end, with both start and end, or just the start or just the end.

Pagination

Pagination is supported by two optional formats: page and size. They can be used together with start and end or on its own.

Note, it works together with start and end parameters.

• start and end filter result set.
• page and size paginate the result set

If you specify pagination, start and end filter by date. Pagination is applied whether or not start and end have been used.

page

An optional parameter that specifies which page of results to return. Works together with size; 1-based.

size

An optional parameter that specifies number of results per page to return. Works together with page. If page is not specified, the page is set to 1 by default. If neither page or size are specified, then all the results will be returned.

Output Format

format

Indicates the encoding of the returned data. csv, json, and html can be specified by using this parameter (e.g. …&format=csv…).

The default output format is HTML. All data contains headers.

Aggregation

sumBy

An optional parameter that mimics SQL GROUP BY in conjunction with the SUM aggregate function. Specifying this parameter forces all metrics to be summed for given dimension(s).

Notes:

• For Totals it does not make sense, since totals resources contain only one dimension (Date).
• This parameter is case-sensitive.

Let’s view attributes as an example. Here is simple data:

Date	Attribute1	Attribute2	Rec Clicks	Directed items	Other metrics
1	men	pants	2	11	…
1	men	skirt	3	12	…
1	women	pants	4	13	…
1	women	skirt	5	14	…
2	men	pants	6	15	…
2	men	skirt	7	16	…
2	women	pants	8	17	…
2	women	skirt	9	18	…

sumBy=RecordDate

Date	Rec Clicks	Directed Items	Other metrics
1	14	50	…
2	30	66	…

sumBy=Attribute1

Attribute1	Rec Clicks	Directed Items	other metrics
men	18	54	…
women	26	63	…

sumBy=RecordDate, Attribute1

Date	Attribute1	Rec Clicks	Directed Items	Other metrics
1	men	5	23	…
1	women	9	27	…
2	men	13	31	…
2	women	17	35	…

You may wonder if the number of sum by parameters is limited to 2. Can you have sumBy=date,attribute1,attribute2?

It does not make sense to do that. In this case you would be summing by all three dimensions. Note: date, attribute1, attribute2 combination should be unique. In fact, if allthree are specified in sumBy, then the output should be identical to the output wihtout any sumBy at all.

What about other groupings? It’s case by case. For instance, totals has only 1 dimension: date. It does not make sense to use any sumBy there. Attributes has 3: date, attribute1, attribute2. In that case it makes sense to use no more than 2 dimensions in sumBy. Products has 2 dimensions: date and product id. In this case it makes sense to use no more than 1 dimension in the sumBy (either date or product id).

Sorting

orderBy

An optional parameter that sorts default output data by a particular grouping of dimensions in ascending order. If orderby is specified, then the output data is sorted by whatever it is specified as orderby value that is valid for that particular grouping. It also specifies whether the sort order is ascending or descending. Note, the parameter is case sensitive.

In more detail…

If no orderBy is given, the system sorts in ASC order by default, using all the dimensions in that grouping.

• totals: recordDate
• products: recordDate, prodcutId
• attributes: recordDate, Attribute1, Attribute1
• recs: recordDate, test group, recSpec
• email: recordDate, campaign

Example

 orderBy=directedItems:ASC,recclicks:DESC

In this case, directedItems is sorted in ASC order, and recClicks in DESC.

Note: for MVP orderBy would only support passing one parameter.

If no ASC/DESC is given for a parameter, then the system uses ASC by default. This is what SQL-92 complaint dbs do.

Resources

Totals

• dailytotalsmetrics
• weeklytotalsmetrics
• monthlytotalsmetrics

Dimensions

• recordDate

Metrics

• Unique Visitors
• Rec Users
• Total Clicks
• Rec Clicks
• Visits
• Page Views
• Lingers
• Rec impressions
• Rec Widget impressions
• Rec engagements
• Directed Orders
• Directed Orders Revenue
• Directed Items
• Directed Items Revenue
• Influenced Orders
• Influenced Orders Revenue
• Influenced Items
• Influenced Items Revenue
• total Orders
• Total Orders revenue
• Total items revenue

Examples

/dailytotalsmetrics?format=csv&start=2013-03-09

/dailytotalsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklytotalsmetrics?format=json&start=2013-03-09

/weeklytotalsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlytotalsmetrics?format=html&start=2013-03-09

/monthlytotalsmetrics?format=json&start=2013-03-09&end=2013-4-10

Attributes

• dailyattributesmetrics
• weeklyatributesmetrics
• monthlyattributesmetrics

Dimensions

• recordDate
• Attribute1 (configurable. e.g. Category)
• Attribute2 (configurable. e.g. Sub-Category)

Metrics

• Red Clicks
• Directed Items
• Directed Items Revenue
• Influenced Items
• Influenced Items Revenue
• Rec impressions
• Rec Widget impressions

Examples

/dailyattributesmetrics?format=csv&start=2013-03-09

/dailyattributesmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyattributesmetrics?format=json&start=2013-03-09

/weeklyattributesmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyattributesmetrics?format=html&start=2013-03-09

/monthlyattributesmetrics?format=json&start=2013-03-09&end=2013-4-10

Products

• dailyproductsmetrics
• weeklyproductsmetrics
• monthlyproductsmetrics

Dimensions

• recordDate
• Products (Top 50 products sorted by Directed Items Revenue)
  • product id (product id attribute name is configurable)
  • product name (product name attribute name is configurable)

Metrics

• Rec Clicks
• Directed Items
• Directed Items Revenue
• Influenced Items
• Influenced Items Revenue
• Rec impressions
• Rec Widget impressions

Examples

/dailyproductsmetrics?format=csv&start=2013-03-09
/dailyproductsmetrics?format=html&start=2013-03-09&end=2013-4-10
/weeklyproductsmetrics?format=json&start=2013-03-09
/weeklyproductsmetrics?format=csv&start=2013-03-09&end=2013-4-10
/monthlyproductsmetrics?format=html&start=2013-03-09
/monthlyproductsmetrics?format=json&start=2013-03-09&end=2013-4-10

Recs

• dailyattributesmetrics
• weeklyattributesmetrics
• monthlyattributesmetrics

Dimensions

• recordDate
• testGroup
• recSpec

Metrics

• Rec Clicks
• Directed Orders
• Directed Orders Revenue
• Directed Items
• Directed Items Revenue
• Influenced Orders
• Influenced Orders Revenue
• Influenced Items
• Influenced Items Revenue
• Rec impressions
• Rec Widget impressions
• Rec engagements

Examples

/dailyrecsmetrics?format=csv&start=2013-03-09

/dailyrecsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyrecsmetrics?format=json&start=2013-03-09

/weeklyrecsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyrecsmetrics?format=html&start=2013-03-09

/monthlyrecsmetrics?format=json&start=2013-03-09&end=2013-4-10

Tests

Dimensions

• recordDate
• testName
• testGroup

Metrics

• Rec Clicks
• Rec Users
• Directed Items
• Directed Items Revenue
• Directed Orders
• Directed Orders Revenue
• Influenced Items
• Influenced Items Revenue
• Influenced Orders
• Influenced Orders Revenue
• Rec impressions

Examples

/dailytestsmetrics?format=csv&start=2013-03-09

/dailytestsmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklytestsmetrics?format=json&start=2013-03-09

/weeklytestsmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlytestsmetrics?format=html&start=2013-03-09

/monthlytestsmetrics?format=json&start=2013-03-09&end=2013-4-10

Email

Dimensions

• recordDate
• campaign

Metrics

• Email Clicks
• Directed Orders
• Directed Orders Revenue
• Directed Items
• Directed Items Revenue
• Influenced Orders
• Influenced Orders Revenue
• Influenced Items
• Influenced Items Revenue

Examples

/dailyemailmetrics?format=csv&start=2013-03-09

/dailyemailmetrics?format=html&start=2013-03-09&end=2013-4-10

/weeklyemailmetrics?format=json&start=2013-03-09

/weeklyemailmetrics?format=csv&start=2013-03-09&end=2013-4-10

/monthlyemailmetrics?format=html&start=2013-03-09

/monthlyemailmetrics?format=json&start=2013-03-09&end=2013-4-10