Chapter 31. Implementing 3scale API analytics to manage and optimize API access

Implementing 3scale API analytics to manage and optimize API access enables you to track items such as usage trends over time. Knowing how your API is used is a crucial step for managing traffic, provisioning for peaks, and identifying users who send the most requests to the API.

3scale gathers API analytics for methods and metrics that you can define at these levels:

  • Product: Hits is the built-in metric that tracks traffic to your API. You can create additional metrics and designate methods in your API for which to capture analytics.
  • 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.

Prerequisites

  • You completed the Getting Started instructions.

    By using the Getting Started guide, you use one of the existing 3scale code plugins to perform an integration.

  • Alternatively, follow a similar flow with other integration methods. See the Operating APIcast chapter of the documentation to learn more about the available integration options.

31.1. 3scale API metrics and methods that capture API use

3scale acts as an infinitely scalable data repository for your API product statistics. You can use metrics and methods to capture API product statistics so that you have the information necessary to optimally manage access to you API. 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.

Once you have chosen the metrics you want to use, register them in the Admin Portal by using the procedure described in Adding metrics to products and backends.

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 uses in the plugin configuration. For more details about creating methods and metrics, see Designating methods and adding metrics for capturing usage details.

31.2. Configuring 3scale plugins to capture API metrics

When 3scale is ready with the names of the metrics you want to track, you need to configure your plugin to report those 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.

Prerequisites

  • You must have already configured metrics for products and/or backends.

Procedure

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

  2. Use the System name method in the metric to report traffic for a specific API method.

    This automatically increments the counter both for the method reported and the Hits metric.

  3. In the Admin Portal, under Account Settings > Integrate → 3scale API Docs, report the traffic using the 3scale Service Management API.

For additional information about different endpoints, refer to the 3scale API Documentation, available in the Admin Portal under Account Settings > Integrate → 3scale API Docs.

31.3. Viewing analytics for 3scale API 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

Procedure

  1. From the Admin Portal dashboard, 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: Select an analytic other than Hits, either a method 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
  4. Click the Download CSV link to download the data in a CSV file.

31.4. Sending test requests to confirm plugin configuration for capturing API metrics

Establish a connection between the API and 3scale so that you can send traffic to the API product and watch it register on the API Analytics dashboard.

Prerequisites

  • A 3scale developer account
  • A 3scale application with API credentials

Procedure

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

  3. Find the API Credentials of 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.

    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 appears in the Analytics section for your API product.

Next steps

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 to further control who sees them. See Creating the Developer Portal for more information about customizing the Developer Portal.

Besides the usage graphs in the Analytics section, you can access analytics data with the Analytics API. The 3scale Analytics API is a flexible way to extract all analytics data for your API product in either XML or JSON format.

31.5. Troubleshooting techniques when analytics are missing for 3scale APIs

If traffic does not display on the usage charts in the [Your_product_name] > Analytics > Traffic, 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: From the Admin Portal Dashboard, navigate to [Your_product_name] > Integration > Methods & Metrics.
    • Backends: From the Admin Portal Dashboard, navigate to [Your_backend_name] > Methods & Metrics.