Chapter 19. Designating methods and adding metrics for capturing usage details

An application plan sets limits and pricing rules for consumer access to your API. To enable enforcement of limits and rules, designate methods in your API for which to collect individual usage data or add metrics. Add a mapping rule to each designated method and each custom metric. The mapping rule specifies details about the usage data that you want to capture.

You can designate methods or add metrics for products and backends. For products, this enables setting limits and pricing rules in the product’s application plans. For backends, this enables setting limits and pricing rules in the application plans for any product that bundles that backend.

Designate methods for which to capture the number of individual calls. This provides finer granularity for tracking API use. Reporting traffic to a method automatically increases counters for the method and for the Hits metric. You can designate a method for each endpoint of your API backend or for a combination of endpoint and HTTP method. See Adding mapping rules to methods and metrics to learn how to map the endpoints of your API to the methods added here.

Metrics are suitable to track the usage of your API, for both products and backends. Hits is the built-in metric that exists for each API. It tracks the number of calls made to your API. To capture usage of your API apart from Hits, define a metric that reports the usage in different units. A unit should be quantifiable and apply a meaning for your business goals such as megabytes, CPU time, or the number of elements returned by the API. Metrics other than Hits, such as CPU time or mb are not provided by default. Obtain these metrics by using an endpoint called by an external service configured by the user.

Methods and metrics are the scaffolding for packaging your API. Each application plan enables you to define different usage limits and pricing rules for each designated method and each metric. See API analytics to learn more about the usage reported by metrics and methods.

19.1. Adding methods to products and backends

Adding a method to a product or backend means that you are designating a method in your API for which you want to capture individual usage details. An application plan provides the ability to set a limit for each method that you add to a product or backend. The procedure for adding a method or metric to a product is similar to adding a method or metric to a backend.

Procedure

  1. Navigate to [Your_product_name] > Integration > Methods & Metrics or [Your_backend_name] > Methods & Metrics.
  2. Click New method.

  3. In the Friendly name field, enter a short description of the method. This name is displayed in different sections of the 3scale Admin Portal. The friendly name must be unique for the product.

    Important

    Be careful with changing the system name of the methods or deleting them. These changes can break your already deployed 3scale integration if there are mapping rules pointing to the previous system name of the method.

  4. In the System name field, enter the name of the method in your API to use to report the usage through the 3scale Service Management API. The system name must conform to these rules:

    • Unique in the product or backend
    • Contain only alphanumeric characters, underscore _, hyphen - or forward slash /
    • No spaces

    Otherwise, you are free to decide what the system name looks like. It can be the same as the endpoint (/status), or, for example, it can include the method and the path (GET_/status).

  5. Optional: In the Description field, enter a more detailed description of the method.
  6. Click Create Method.

Verification steps

  • Added methods are available in your application plans.

Next steps

  • Edit limits and pricing rules for each method by going to [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit].

19.2. Adding metrics to products and backends

Adding a metric specifies a usage unit that you want to capture for all calls to your API. An application plan provides the ability to set a limit for each metric that you add to a product or backend. The procedure for adding a method or metric to a product is similar to adding a method or metric to a backend.

Procedure

  1. Navigate to [Your_product_name] > Integration > Methods & Metrics or [Your_backend_name] > Methods & Metrics.
  2. Click New metric.

  3. In the Friendly name field, enter a short description of the metric. This name is displayed in different sections of the 3scale Admin Portal. The friendly name must be unique for the product.

    Important

    Be careful with changing the system name of the metrics or deleting them. These changes can break your already deployed 3scale integration if there are mapping rules pointing to the previous system name of the metric.

  4. In the System name field, enter the name of the metric in your API to use to report the usage through the 3scale Service Management API. The system name must conform to these rules:

    • Unique in the product or backend
    • Contain only alphanumeric characters, underscore _, hyphen - or forward slash /
    • No spaces

    Otherwise, you are free to decide what the system name looks like.

  5. In the Unit field, enter the unit.

    • Use a singular noun, for example, hit. The singular will become plural in the analytics charts.
  6. Optional: In the Description field, enter a more detailed description of the metric.
  7. Click Create Metric.

Verification steps

  • Added metrics are available in your application plans.

Next steps

  • Edit limits and pricing rules for each metric by going to [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit].
  • Map your metrics to one or more URL pattern by going to [Your_product_name] > Integration > Mapping Rules. See Adding mapping rules to methods and metrics.

19.3. Alternatives for importing methods and metrics

If your API has multiple endpoints, there are two ways to automatically designate methods and add metrics to 3scale products and backends:

19.4. Adding mapping rules to methods and metrics

Mapping rules are operations that are mapped to previously created methods and metrics in your products and backends.

Note

Mapping rules are required in your previously created methods, however, they are optional for metrics.

Procedure

  1. Navigate to [Your_product_name] > Integration > Mapping Rules.
  2. Click Add Mapping Rule.
  3. The Verb field is pre-populated with the HTTP method, GET, however you can select other options from the dropdown list.
  4. In the Pattern field, add a valid URL that starts with an forward slash /. The URL can be from a wildcard you specified inside curly brackets {}.
  5. In the Metric or Method to increment field, select from one of your previously created methods or metrics.
  6. The Increment by field is pre-populated with 1, however, change this to suit your own needs.
  7. Click the Create Mapping Rule button.

Verification steps

  • To verify your mapping rules, navigate to [Your_product_name] > Integration > Methods & Metrics. Each method and metric should have a check mark in the Mapped column.

19.5. Additional resources