Security stats API

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

The security stats API lets you view abuse and bot-related statistics over the past 14 days. There are two type of security stats:

• Tabular stats, which don't have a time dimension. Tabular stats are often computed using an aggregation function, for example, sum for message_count or bot_traffic.
• Time series stats, which do have a time dimension.

Parameters in example API calls

The following sections give examples of API calls that use the security stats API. The API calls contain the following parameters:

• ORG: Your organization.
• ENV: Your environment.
• METRIC_i: A metric for the statistic. See Metrics and aggregation functions.
• AGGREGATION_i: An aggregation function for the metric. See the table below.
• DIMENSION_i: A dimension for grouping the values of the statistic.
• PAGE_SIZE: Maximum number of subcomponents returned in a single page.
• time_range: The time range for the statistics in the form

  "time_range": {
      "start_time": START_TIME,
      "end_time": END_TIME
  }

  where:

  • START_TIME is the start time for the time range.
  • END_TIME is the end time for the time range.

  START_TIME and END_TIME are of the form "YYYY-MM-DDT00:00:00Z".

  The length of the time range can be at most 14 days, and both the start date and end date must be within the past 365 days.

Example: Query tabular security stats for an environment

A request that queries tabular stats has the following format:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

See Parameters in example API calls.

See Limitations on security stats for the maximum numbers of metrics, aggregation functions, and dimensions that can be included in a request.

Here is an example of a request that queries tabular stats:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

See the queryTabularStats reference page for descriptions of the request and response.

Example: Query time series security stats for an environment

Time series APIs return time series stats for the chosen metrics, grouped by the chosen dimension.

The following call invokes time series stats for bot traffic grouped by API proxy. Since there are four proxies, this yields four sequences of time series points. The order of the points of each row match the corresponding index in the columns field.

Here is a sample request:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

See Parameters in example API calls.

See the queryTabularStats reference page for descriptions of the request and response.

Example: Query incident details for abuse detection

The following example queries the details of an incident for Advanced API Security's Abuse detection. The call returns details for bot count for the developer_app for a given incident.

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

See Parameters in example API calls.

This returns a response like the following:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

See the queryTabularStats reference page for descriptions of the request and response.

Metrics and aggregation functions

The following table describes the metrics and aggregation functions available in the security stats API:

Dimensions

Dimensions let you group metric values together based on related subsets of the data. The following table describes the dimensions that are specific to Advanced API Security reports:

Note: bot_reason and incident_id only work with the following metrics:

• bot
• bot_traffic
• response_size

In addition to the dimensions described above, Advanced API Security also supports the following dimensions:

• access_token
• api_product
• apiproxy
• ax_edge_execution_fault_code
• ax_geo_city
• ax_geo_continent
• ax_geo_country
• ax_geo_region
• ax_isp
• ax_resolved_client_ip
• ax_ua_agent_version
• client_id
• developer
• developer_app
• developer_email
• environment
• proxy_basepath
• proxy_pathsuffix
• request_uri
• response_status_code
• target_url
• useragent

Limitations on security stats

The security stats API (both tabular and time series) has the following limits:

• Maximum page size: 14400
• Maximum of 10 time series dimensions
• Maximum of 15 tabular stats dimensions
• Maximum of 5 metric aggregations.
• Maximum of 5 time series metric aggregations
• Time range: Length can be at most 14 days, and both the start date and end date must be within the past 365 days.
• The dimensions incident_id and bot_reason cannot be used with the metrics message_count or response_size.

Comparing the security stats API and the security reports API

Both the security stats API and the security reports API return abuse and bot-related security statistics, but they have the following differences:

• The security stats API is designed to view statistics for recent API traffic. Data for the security stats API goes back only 14 days, but you can view the stats immediately when you send a request.

  Security stats are also displayed in the Abuse metrics view in the Apigee UI.

• The security reports API is designed to view statistics for long-running operations. To use the security scores API, you submit a job and view the results only when the job is completed. Data for the security scores API goes back one year.