Chapter 31. API analytics

This guide is designed to help you tune the API analytics to track the items you need to know about, such as checking the most used applications and trends over time. Knowing how your API is used is a crucial step for managing traffic, provisioning for peaks, and identifying users who mostly send requests to the API.

3scale tracks API analytics via methods and metrics that you can define in these levels:

  • Product: Hits metric counts hits mapped to Hits itself and to its corresponding methods, in addition to all the hits mapped to the backend-level Hits metrics and their methods.
  • Backend: 3scale registers methods and metrics in the backend as if they belong to each product using the API backend. You can set limits and pricing rules for the backend-level metrics in the Application Plans defined at the Product level.
  • Application: You can obtain analytics reports for each application created in 3scale.

31.1. Prerequisites

Complete the instructions of the Getting Started section 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 Operating APIcast chapter of the documentation to learn more about the available integration options.

31.2. Determining the metrics and methods to track

3scale acts as an infinitely scalable data repository for your API product statistics, and you can track almost any metric for your API product. For example:

  • Hits/transactions: calls to the API product. Hits are included by default as metrics on all APIs. Hits can be overall calls to the API product or broken out into individual methods on the API product.
  • Data transfer: quantity of MB/GB of data uploaded and downloaded via the API product
  • CPU hours: compute time (or some other internal resource) associated with calls to the API product
  • 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 product. 3scale can track an arbitrary number of metrics and methods, as long as it is a countable quantity that can be incremented over time.

31.3. Creating your metrics and methods

After you choose your metrics, register them in the Admin Portal:

  • To add methods and metrics to your product, navigate to [Your_product_name] > Integration > Methods & Metrics.
  • To add methods and metrics to your backend, navigate to [Your_backend_name] > Methods & Metrics.

You can add metrics and methods to the product or backend you have selected. Provide them with a friendly name and a system name, which 3scale use in the plugin configuration. For more details about creating methods and metrics, see defining your API on 3scale.

31.4. Setting up reports

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.

To set up reports, consider the following:

  • 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.
  • When you report traffic for a specific API method, use the system name method in the metric argument. This automatically increments the counter both for the method reported and the hits metric.
  • You can also report the traffic using the 3scale Service Management API. For additional information about different endpoints, refer to 3scale APIs ActiveDocs, available in your Admin Portal under the Documentation → 3scale API Docs section.

31.5. Checking analytics for backends

You can view the traffic data for a given API configured as a backend. The Traffic page shows the hits to the endpoint.

Prerequisites

  • Create an API backend.
  • Add the backend to an API product.

Procedure

  1. Navigate to [Your_backend_name] > Analytics.
  2. Choose the time frame for the report. You can choose to show the last 24 hours, 7 days, 30 days, 12 months; or indicate a period of time.

  3. Optional: You can also select a different metric other than Hits; either a method metric or another top level metric.

    • You will see the results in the chart. If there is no traffic to report, you will see the following message: There is no data available for the selected period

You can also download the data in a CSV file. To do so, click the Download CSV link.

31.6. Checking analytics for applications

Once the API and 3scale establish a connection, you can send traffic to the API product 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:

  1. To see the list of existing applications, navigate to Audience > Applications > Listing.
  2. Select an application by clicking on its name.

  3. 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 31.1. API credentials

    API credentials
  4. Use these keys to make calls to your API in the usual 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 product. Traffic from these calls appear in the Analytics section for your API product.

31.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 can hide the analytics views from the Developer Portal. See the Creating the Developer Portal section to learn more about customizing the Developer Portal.

31.8. Accessing analytics data by API and email reports

Besides the usage graphs in the Analytics section, you can access analytics data with:

  • Analytics API

    3scale Analytics API is a flexible way to extract all the analytics data for your API product in either XML or JSON format.

31.9. 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 [your_product_name] > Analytics > 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.

  • Are mapping rules properly mapped to the metrics?

    If mapping rules are not properly mapped to the metrics, you may not see data in the Analytics. Check that the mapping rules are correctly mapped to the metrics, both for API products and API backends:

    • Products: Navigate to [Your_product_name] > Integration > Methods & Metrics.
    • Backends: Navigate to [Your_backend_name] > Methods & Metrics.