Chapter 9. Defining your API (Methods And Metrics)
You can define your API by adding methods and metrics at both the API product and backend levels. An API product is a bundle of one or more API backends. At the product level, methods and metrics enable you to set limits and pricing rules for any of the product’s application plans. At the backend level, methods and metrics can be used to set the limits and pricing rules of the application plan of any product that bundles the backend.
Metrics are suitable to track the usage of your API, both at product and backend levels. Hits is the built-in metric that exists in each API and is used to track the hits made to your API. You can achieve finer granularity for the API usage tracking by defining Methods under the Hits metric. Reporting traffic to a method automatically increases counters for the method and for the Hits metric. You can define separate methods for each endpoint of your API backend, or a combination of endpoint and HTTP method. See the Mapping rules section to learn how to map the endpoints of your API to the methods defined here.
For measuring usage of your API apart from hits, you can define a new Metric and report the usage in different units. A unit should be quantifiable and apply a meaning for your business goals such as megabytes, CPU time, the number of elements returned by the API, and so on. All metrics other than hits, such as CPU time or mb, are not included by default on 3scale and must be reported using an endpoint periodically called by an external service configured by the user.
Methods and metrics are also the scaffolding to package your API: each application plan enables you to define different usage limits and pricing rules for each method and metric. See the API analytics section to learn more about the usage reported to metrics and methods.
Additional resources
For more details on API products and backends, see Getting started with 3scale.
9.1. Adding methods and metrics
To add a new method to a product or backend, follow these steps:
- Navigate to [Your_product_name] > Integration > Methods & Metrics or [Your_backend_name] > Methods & Metrics.
- Click on the New method link, placed on the right above the list of methods.
Specify the parameters:
- Friendly name is a short description of the method, it is shown in different sections of the 3scale Admin Portal. This name must be unique for the product.
-
System name is the name of the method which will be used to report the usage through the 3scale Service Management API. It also must be unique, and it should only contain alphanumeric characters, underscore
_, hyphen-and forward slash/without spaces. Other than that, you are free to decide what the system name will look like, it can be exactly the same as the endpoint (/status), or for example can include the method and the path (GET_/status). The Description field can be used for a more detailed description of the method, it is optional.
- Finally, click Create Method.
You can later change the definition of the method. Just click on the method name (in the column Method), update the fields and click on Update Method.
Be very careful with changing the system name of the methods and 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 method.
For creating a new metric, click on New metric and provide the required parameters. When specifying the unit, use a singular noun (e.g. "hit"), as it will be pluralized automatically in the Analytics charts.
These new methods and metrics will be available in all of your current and future plans. You can now edit limits and pricing rules for them on each plan by going to [Your_product_name] > Applications > Application Plans > [plan_you_want_to_edit].
9.2. Importing your methods and metrics automatically
If your API has a lot of endpoints, we offer two additional ways of automatically creating your methods and metrics on 3scale:
