This topic covers the Analytics API exposed by the APi Platform. The examples are based on the Apigee API Dashboard App. The Analytics API provides RESTful resources for creating reports from the data collected by the API Platform, enabling developers to explore how an API performs, and how, and by whom, it is consumed.
Building a Report: Dimensions, Functions, and Metrics
A report is constructed from a set of parameters:
- Dimensions: The dimension selected from the list of dimensions recorded by Apigee, represented as URI parameter. If no dimension is defined, then the report generated represents all message traffic across all Apis in an environment.
- Metrics: The metric calculated for the chosen dimension. Represented as a query parameter.
- TimeRange: The time interval over which data should be analyzed.
- Functions: The calculation run against the metric defined for the dimension.
- Filters: A set of query parameters that can be used to filter and drill-down into results, to generate reports, for example, on the "top 10" results, to filter results on specific dimension names, to sort results.
For complete reference on these parameters, see the User Guide topic Build custom reports
Custom variables can also be used to create dimensions specific to message content. See the Custom Analytics Developer Guide topic.
The dimension that defines a report is represented in the request by a URI parameter.
For example, to build a report based on API metrics:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apis
To build a report based on developer metrics:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/developers
To build a report based on developer app metrics:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/developer_apps
To build a report based on API metrics across all environments, a wildcard URI pattern is supported:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/*/stats/apis
The example below collects a sum of message count for all APIs. The report provides a snapshot of the throughput to all APIs in the environment specified (in this case, 'test'):
$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?'select=sum(message_count)&timeRange=7/24/2012%2000:00~8/25/2012%2000:00&timeUnit=day'
Sample Response
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1343088000000,
"value" : "5.0"
}, {
"timestamp" : 1343174400000,
"value" : "0"
} ]
} ],
"name" : "myAPI"
}, {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1343088000000,
"value" : "0"
}, {
"timestamp" : 1343174400000,
"value" : "2.0"
} ]
} ],
"name" : "weatherAPI"
} ],
"name" : "test"
} ],
"metaData" : {
"samplingRate" : "100"
}
}
You can select other dimensions to build reports on. For example, you can specify the 'target_url' dimensions to retrieve metrics on backend services. The following report shows the total throughput to target URLs for the specified time interval:
$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/target_url?'select=sum(message_count)&timeRange=7/24/2012%2000:00~8/25/2012%2000:00&timeUnit=day''
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1344816000000,
"value" : "1.0"
}, {
"timestamp" : 1345075200000,
"value" : "8.0"
}, {
"timestamp" : 1345161600000,
"value" : "8.0"
} ]
} ],
"name" : "https://api.partner.com"
}, {
"metrics" : [ {
"name" : "sum(message_count)",
"values" : [ {
"timestamp" : 1344816000000,
"value" : "3.0"
}, {
"timestamp" : 1345075200000,
"value" : "0"
}, {
"timestamp" : 1345161600000,
"value" : "3.0"
} ]
} ],
"name" : "http://weather.yahooapis.com/forecastrss?w=12797282&"
} ],
"name" : "test"
} ],
"metaData" : {
"samplingRate" : "100"
}
}
Get a count of error messages returned by target URLs for the past week
The sample report below defines the dimension target_url, and the metric count for theis_error variable. This variation on the report will show how many errors were returned by all target URL in the 'test' environment:
$ curl -u myname:mypass -H "Content-type:application/octet-stream" 'https://api.eterprise.apigee.com/v1/o/{org_name}/environments/test/stats/target_url?select=count(is_error)&timeRange=8/08/2012%2000:00~8/15/2012%2000:00&timeUnit=week'
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "count(is_error)",
"values" : [ {
"timestamp" : 1344211200000,
"value" : "44.0"
}, {
"timestamp" : 1344816000000,
"value" : "1.0"
} ]
} ],
"name" : "https://api.company.com"
}, {
"metrics" : [ {
"name" : "count(is_error)",
"values" : [ {
"timestamp" : 1344211200000,
"value" : "23.0"
}, {
"timestamp" : 1344816000000,
"value" : "3.0"
} ]
} ],
"name" : "http://weather.yahooapis.com/forecastrss?w=12797282&"
}, {
"metrics" : [ {
"name" : "count(is_error)",
"values" : [ {
"timestamp" : 1344211200000,
"value" : "0"
}, {
"timestamp" : 1344816000000,
"value" : "12.0"
} ]
} ],
"name" : "http://weather.yahooapis.com/forecastrss?w=12797282&"
} ],
"name" : "test"
} ],
"metaData" : {
"samplingRate" : "100"
}
Get the top target URL by error rate for the week
The 'topk' (meaning 'top k' entities) enables reporting on the top entities for a given metric. For example, to find which target URLs was the most error prone over the last week, the topk parameter is appended to the request, with a value of 1.
For example you may be interested to know who your top developer are, measured by throughput, what your worst (i.e., 'top slowest') target APIs are by latency:
$ curl -u myname:mypass -H "Content-type:application/octet-stream" 'https://api.eterprise.apigee.com/v1/o/apigee-cs/environments/test/stats/target_url?select=count(is_error)&timeRange=8/08/2012%2000:00~8/15/2012%2000:00&timeUnit=week&sortby=count(is_error)&topk=1'
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "count(is_error)",
"values" : [ {
"timestamp" : 1344816000000,
"value" : "1.0"
}, {
"timestamp" : 1344211200000,
"value" : "44.0"
} ]
} ],
"name" : "https://api.company.com"
} ],
"name" : "test"
} ],
"metaData" : {
"samplingRate" : "100"
}
}
The result of this request is a report that shows that the buggiest target URL is http://api.company.com.
Get statistics for top APIs
The following example generates a report on the top ranked API, defined by highest throughput in the last week:
$ curl -u myname:mypass 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?select=message_count&timeRange=7/24/2012%2000:00~8/25/2012%2000:00&timeUnit=week&sortby=message_count&sort=DESC&topk=1'
Sample Response
{
"environments" : [ {
"dimensions" : [ {
"metrics" : [ {
"name" : "message_count",
"values" : [ {
"timestamp" : 1345420800000,
"value" : "14.0"
}, {
"timestamp" : 1344816000000,
"value" : "8.0"
}, {
"timestamp" : 1344211200000,
"value" : "111.0"
}, {
"timestamp" : 1343606400000,
"value" : "405.0"
} ]
} ],
"name" : "weatherAPI"
} ],
"name" : "test"
} ],
"metaData" : {
}
}
Summary: analytics calls made by the Apigee API dashboard app
All API Traffic
$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/?select=message_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&sortby=message_count&timeUnit=hour
Top API Movers
$ curl -u myname:mypass 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apis?select=message_count,error_count,&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=message_count&timeUnit=hour'
Top API Products
$ curl -u myname:mypass 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apiproducts?select=message_count,app_count,developer_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=app_count&timeUnit=hour'
Top Ranked Apps
$ curl -u myname:mypass 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/apps?select=message_count,error_count,user_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=user_count&timeUnit=hour''
Top Ranked Developers
$ curl -u myname:mypass 'https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/stats/devs?select=message_count,error_count,user_count&timeRange=7/14/2012%2013:00~8/13/2012%2013:00&sort=ASC&topk=5&sortby=user_count&timeUnit=hour'
Post questions to the Apigee Developer Forum.
Back to API Platform Developer Guide.
