Being aware of how your API is being 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.
You'll need to have done the basics of connecting your API to 3scale to proceed with this guide.
The guide assumes that you're doing the integration using one of the existing 3scale code plugins, but you can follow a similar flow with other integration methods. Check the deployment options section of the documentation to learn more about the available integration options.
Step 1: Determine the metrics and methods you want to track
3scale acts as an infinitely scalable data repository for your API stats, and you can track pretty much any metric you want for your API. For example:
- Hits/transactions: these are 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.
And many more might be relevant to your API. 3scale can track an arbitrary number of metrics and methods, as long as it's a countable quantity that can be incremented over time.
Step 2: Create your metrics and methods
After you have chosen your metrics, you need to register them in the 3scale Admin Portal. Navigate to the the Dashboard > API section, and select Definition for the API you wish to manage.
Add metrics and methods to the service, and provide them with a friendly name and a system name. The system name is used later in your plugin configuration. For more details about creating methods and metrics, check out our tutorial about defining your API on 3scale.
Step 3: Set up reporting
Once the 3scale system has been configured with the names of the metrics you wish to track, it's time to tweak your plugin setup to report the right metrics. The precise manner of doing this will depend on the plugin or integration method in use. In general, you need to follow the these steps:
- By default the plugins will report the hits (API transactions) metric only.
- Taking the list of metric and method system names, 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.
When you report traffic for a specific API method, you should use the method system name in the metric argument. This automatically increments the counter both for the method reported and the hits metric.
Step 4: Check that traffic is being correctly reported
Now that the connection between the API and 3scale has been established, you can begin to send traffic to the API and watch it register on the API Analytics dashboard. For the next steps, you will need an existing developer account and an application with API credentials. If you don't have those yet, head to the hello world guide. Then do the following:
- Navigate to Dashboard > Applications to see the list of existing applications, and select one of them by clicking on its name.
- Find the API credentials for the selected application. The credentials will depend on the selected authentication type and can be one of the following: user key (API key), application ID and application keys, or client ID and client secret. For more information about the available authentication modes, check the authentication patterns article.
- Use these keys to make calls to your API in the normal way (e.g. from the command line using cURL or from the browser for API endpoints using GET method). The precise calls to make will depend on the structure of the methods on your API.
Traffic from these calls should appear in the Analytics section for your API.
If traffic is not showing up on the usage charts in the Analytics section, check the following:
- 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.
- 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 your API settings of your Admin Portal. Check that you're 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.
Controlling who sees the analytics
By default the usage statistics are visible both to the API provider though the Admin Portal as well as to developers who created applications though the Developer Portal (each developer can only see the usage statistics for their own applications). However, you can hide the analytics views from the Developer Portal if you want to. Check the Developer Portal section to learn more about how to customize the Developer Portal.
Asynchronous and batch traffic reporting
Typically the API usage is reported to 3scale after each call. However, the following approaches can be also used:
- Asynchronous traffic reports
If you're using plugin integration, you can make report calls asynchronously and avoid additional latency in your API. APIcast deployment options provided by 3scale (hosted, self-managed) use this approach by default.
- 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.
Accessing analytics data by API and email reports
Besides the usage graphs in the Analytics section, there are a couple more ways of getting the analytics data for your API:
- Daily and weekly traffic reports
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 checkboxes: "weekly aggregate reports" and "daily aggregate reports". If enabled, these reports are emailed to the admin user of your 3scale account.
- CSV export
On each analytics view page, you will find a download CSV link, which allows you to download the usage statistics in CSV format.
- Analytics API
You can also 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. Please check the Analytics API section of the 3scale APIs ActiveDocs page.