Chapter 1. API analytics
This guide is designed to help you tune your API analytics to track the items you need to know about and to see top applications and trends over time.
Knowing how your API is used is a crucial step for managing traffic, provisioning for peaks, and identifying top users so you can help them achieve greater success with your API.
1.1. Prerequisites
Complete the basics of connecting your API to 3scale before using this guide.
The guide assumes that you are using one of the existing 3scale code plugins to perform an integration. You can follow a similar flow with other integration methods. Check the APIcast Overview chapter of the documentation to learn more about the available integration options.
1.2. Determine the metrics and methods you want to track
3scale acts as an infinitely scalable data repository for your API statistics, and you can track almost any metric for your API. For example:
- Hits/transactions: calls to the API. Hits are included by default as metrics on all APIs. Hits can be overall calls to the API or broken out into individual methods on the API.
- Data transfer: quantity of MB/GB of data uploaded and downloaded via the API
- CPU hours: compute time (or some other internal resource) associated with calls to the API
- Results returned: count of the number of records or data objects being returned
- Disk storage: total disk storage in use by an account
You can track more metrics that are relevant to your API. 3scale can track an arbitrary number of metrics and methods, as long as it is a countable quantity that can be incremented over time.
1.3. Create your metrics and methods
After you chose your metrics, register them in the 3scale Admin Portal. Navigate to the the Dashboard > API section and select Definition for the API you want to manage.
Figure 1.1. Create new method
Add metrics and methods to the service. Provide them with a friendly name and a system name, which is used later in your plugin configuration. For more details about creating methods and metrics, see defining your API on 3scale.
1.4. Set up reporting
Once you have configured the 3scale system with the names of the metrics to track, it is time to tweak your plugin setup to report the right metrics. The precise manner of doing this depends on the plugin or integration method in use. By default, the plugins report the hits (API transactions) metric only.
Generally speaking, you need to follow these steps.
- The application should pass the appropriate metric/method names to the plugin as determined by the incoming API call. The metric/method value and the increment required is an argument of authorize and/or report methods the plugin exposes.
-
You can also report the traffic using the 3scale Service Management API. You can find information about different endpoints in the 3scale APIs ActiveDocs section. 3scale ActiveDocs are available in your Admin Portal under the Documentation
3scale API Docs section.
When you report traffic for a specific API method, use the method system name in the metric argument. This automatically increments the counter both for the method reported and the hits metric.
1.5. Check that traffic is reported correctly
Once the API and 3scale connection is established, you can send traffic to the API and watch it register on the API Analytics dashboard. You need an existing developer account and an application with API credentials to be able to perform the steps in this section. Follow these steps to create a developer account and get an application with API credentials.
- Open the Getting Started guide.
-
Navigate to Dashboard
Applications in the API Analytics dashboard to see the list of existing applications. Select an application by clicking on its name.
Figure 1.2. Applications
Find the API credentials for the selected application. The credentials depend on the selected authentication type and can be a user key (API key), an application ID and application keys, or a client ID and client secret. For more information about the available authentication modes, see the authentication patterns article.
Figure 1.3. API credentials
Use these keys to make calls to your API in the normal way (for example, from the command line using cURL or from the browser for API endpoints using the GET method). The precise calls to make depend on the structure of the methods on your API. Traffic from these calls appear in the Analytics section for your API.
Figure 1.4. Analytics usage
1.6. Troubleshooting
If traffic does not display on the usage charts in the Analytics section, perform the following checks.
Are authorize/report calls responding correctly?
All plugins call the 3scale Service Management API, which has predetermined response codes. Authorize calls for valid keys should return responses with HTTP code 200. Report calls should respond with code 202.
Are there errors in the integration error console?
The log of integration errors detected by 3scale can be found in Analytics
Integration errors. Figure 1.5. Integration errors
Are the correct metric and method names being used?
The most common reason for failure is that the method and metric names passed in report calls do not correspond to those created in the API settings of your Admin Portal. Check that you are using the correct system names for each metric/method.
You can also check which metrics are being reported to 3scale in the Analytics
Traffic section. Figure 1.6. Analytics traffic
1.7. Controlling who sees the analytics
By default, the usage statistics are visible to the API provider through the Admin Portal and to the developers who created applications through the Developer Portal. (Each developer can see only the usage statistics for their own applications.) You have the ability to hide the analytics views from the Developer Portal. See the Developer Portal section to learn more about customizing the Developer Portal.
1.8. Asynchronous and batch traffic reporting
The API usage is usually reported to 3scale after each call; however, the following approaches can be also used.
Asynchronous traffic reports
If you use plugin integration, you can make report calls asynchronously and avoid additional latency in your API. Deployment options provided by 3scale (hosted, self-managed) use this approach by default. See APIcast for more details.
Batch reports
You can also report in batches rather than call-by-call by bundling groups of calls together and sending the reports for them on a minute-by-minute basis or by some other criteria.
1.9. Accessing analytics data by API and email reports
Besides the usage graphs in the Analytics section, there are other methods of getting your API’s analytics data.
Analytics API
You can use the 3scale Analytics API. It is a flexible way to extract all the analytics data for your API in either XML or JSON format.
Daily and weekly traffic reports (SaaS only)
These reports provide the aggregated data about your traffic, including information about new subscribers to your API and top applications. To enable these reports in the Account > Notifications section of your Admin Portal, find the weekly aggregate reports and daily aggregate reports check boxes. If enabled, these reports are emailed to the admin user of your 3scale account.
CSV export (SaaS only)
There is a download CSV link on each analytics view page, and you can download the usage statistics in .csv format.
Download CSV image::guides-api-analytics-download-csv.png[width=100px]
