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
- 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
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