API events
Reference table and example use cases for API event based engagement rules.
The following are some of the example use cases for API event based engagement rules:
- An API Provider can use Engagement to get notified:
- If there are more than 3 HTTP 500 errors on any single API in any 24 hr period.
- When the average response time for an API goes beyond a certain threshold.
- A corporate security officer can use engagement to receive an email if someone accesses their banking APIs from an embargoed country.
- An AI API Provider can use engagement to get notified if the total of the AI Tokens used within an hour goes beyond a certain threshold.
The following table shows the list of fields available for an API event record.
| Field name | Type | Description |
|---|---|---|
| ai_cache_hit | Boolean | Indicates whether the AI response was served from cache. |
| ai_model | String | The name or identifier of the AI model that is used. |
| ai_request_tokens | Number | The number of tokens in the input prompt to the AI model. |
| ai_response_tokens | Number | The number of tokens that are generated in the AI response. |
| ai_total_tokens | Number | The total number of tokens that are used in the AI interaction that includes both request and response. |
| alert_action | String | The action that is taken in response to an alert. |
| alert_description | String | The description or message that is associated with the alert. |
| alert_source | String | The source system or module that generated the alert. |
| alert_type | String | The type or category of the alert. |
| api_id | String | The API identifier. |
| api_name | String | The name of the API. |
| api_resource_id | String | Field format is: api_name:api_version:method:path. Only available on API
Gateway v10.5.3 or higher. |
| api_version | String | The version number of the API. |
| api_type | String | The type of API. For example, REST, GraphQL, SOAP. |
| app_id | String | The identifier for the registered application. |
| app_lifecycle_state | String | The lifecycle state of the application. |
| app_name | String | The name of the registered application. Note: The property is set to
undefined when a client ID is not used or is invalid on the API. The gateway needs
a client ID to determine which app was invoking the API. From this app, the gateway can determine
what plan the app is subscribed to on the product that contains the API. Without a client ID, the
gateway is unable to determine what plan, product, or app was invoked, because a single API can
belong to multiple products (each of which have multiple plans and apps that are subscribed to those
plans with client IDs). |
| app_type | String | The application type, with a value of Production or
Development. |
| backend_method | String | The HTTP method that is used in the backend request. |
| backend_request_body | String | The body content of the backend request. |
| backend_request_headers | Object | The headers that are sent in the backend request. |
| backend_response_body | String | The body content of the backend response. |
| backend_response_headers | Object | The headers that are received in the backend response. |
| backend_status_code | String | The HTTP status code returned by the backend. |
| backend_time_to_serve_request | Number | Time in milliseconds taken by the backend to serve the request. |
| backend_url | String | The URL of the backend service invoked. |
| bytes_received | Number | The number of bytes received from the consumer in the request. |
| bytes_sent | Number | The number of bytes sent to the consumer in the response. |
| cached_response | Boolean | Indicates whether the response was served from a cache. |
| callback_request | Boolean | Indicates whether the request was a callback. |
| catalog_id | String | The Identifier of the API catalog. |
| catalog_name | String | The name of the API catalog. |
| client_geoip.area_code | Number | The public switched telephone network (PSTN) area code of the client, as identified from its IP address. |
| client_geoip.city_name | String | The city name of the client, as identified from its IP address. |
| client_geoip.continent_code | String | The two-letter continent code of the client, as identified from its IP address. |
| client_geoip.country_code2 | String | The two-letter country code of the client, as identified from its IP address. |
| client_geoip.country_code3 | String | The three-letter country code of the client, as identified from its IP address. |
| client_geoip.country_name | String | The country name of the client, as identified from its IP address. |
| client_geoip.dma_code | Number | The Designated Market Area (DMA) code of the client, as identified from its IP address. |
| client_geoip.ip | String | The IP address of the client. |
| client_geoip.latitude | Number | The latitude of the client location, as identified from its IP address. |
| client_geoip.location | String | The longitude and latitude of the client location (separated by a comma), as identified from its IP address. |
| client_geoip.longitude | Number | The longitude of the client location, as identified from its IP address. |
| client_geoip.postal_code | String | The postal code of the client, as identified from its IP address. |
| client_geoip.region_code | String | The region code based on client IP. |
| client_geoip.region_name | String | The abbreviated form of the region that corresponds to the IP address of the client. |
| client_geoip.timezone | String | The time zone of the client, as identified from its IP address. |
| client_id | String | The unique ID of the client that is attached to the API request. |
| client_ip | String | The IP address of the client. |
| consumer_organization_id | String | The Identifier of the consumers organization. |
| consumer_organization_name | String | The name of the consumers organization |
| consumer_organization_title | String | The title or display name of the consumer organization. |
| custom_data | Array map | Custom data can be added to this field. |
| datetime | Date | A timestamp that records when the API was invoked. The timestamp is always shown in Coordinated Universal Time. |
| developer_org_id | String | The identifier for the consumer organization that owns the application. |
| developer_org_name | String | The name of the consumer organization that owns the application. |
| endpoint_url | String | When the request failed, endpoint_url identifies the proxy or invoke target
URL on which the request failed. It is not included with a successful request. On V5 compatible
gateway, this field is only populated when the backend server URL that was invoked returns an HTTP
404 code. |
| error_description | String | A detailed description of any error encountered. |
| error_message | String | A brief message describing the error. |
| event_type | String | The type of event. |
| filter_name | String | The name of the filter that is applied during the request. |
| gateway_geoip.area_code | Number | The public switched telephone network (PSTN) area code of the gateway, as identified from its IP address. |
| gateway_geoip.city_name | String | The city name of the gateway, as identified from its IP address. |
| gateway_geoip.continent_code | String | The two-letter continent code of the gateway, as identified from its IP address. |
| gateway_geoip.country_code2 | String | The two-letter country code of the gateway, as identified from its IP address. |
| gateway_geoip.country_code3 | String | The three-letter country code of the gateway, as identified from its IP address. |
| gateway_geoip.country_name | String | The country name of the gateway, as identified from its IP address. |
| gateway_geoip.dma_code | Number | The Designated Market Area (DMA) code of the gateway, as identified from its IP address. |
| gateway_geoip.ip | String | The IP address of the gateway. |
| gateway_geoip.latitude | Number | The latitude of the gateway location, as identified from its IP address. |
| gateway_geoip.location | String | The longitude and latitude of the gateway location (separated by a comma), as identified from its IP address. |
| gateway_geoip.longitude | Number | The longitude of the gateway location, as identified from its IP address. |
| gateway_geoip.postal_code | String | The postal code of the gateway, as identified from its IP address. |
| gateway_geoip.region_name | String | The abbreviated form of the region that corresponds to the IP address of the gateway. |
| gateway_geoip.timezone | String | The time zone of the gateway, as identified from its IP address. |
| gateway_host_name | String | The hostname of the API gateway. |
| gateway_ip | String | The IP address of the gateway. |
| gateway_port | Number | The port number used by the API gateway. |
| gateway_service_name | String | The name of the DataPower API gateway service. Configured by the cloud admin user when registering the gateway service. Only available on DataPower API Gateway v10.5.3 or higher. |
| gateway_time_to_serve_request | Number | Time in milliseconds taken by the gateway to serve the request. |
| gateway_type | String | The type and version of the gateway that processed the call, in format:
type/version. Set by all gateway types except for v5c, and only
available on v10.0.8.0 or higher. |
| global_transaction_id | String | The DataPower global transaction ID. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varserviceglobal-transaction-id-servicevarsglobaltransactionid. |
| graphql_document_hash | String | The hash value of the GraphQL query document. |
| graphql_error_count | Number | The number of errors encountered in the GraphQL query execution. |
| graphql_operation_name | String | The name of the GraphQL operation. |
| graphql_operation_type | String | The type of the GraphQL operation. |
| graphql_request_field_cost | Number | GraphQL APIs only. The maximum cost of all fields accessed in the query. The cost of each field access is configured in the schema. |
| graphql_request_max_nesting | Number | GraphQL APIs only. The maximum nesting depth found in the query by the assembly validate action. The schema configuration is used to determine which types are nested, so this value might be less than the nesting depth found by the assembly parse action. |
| graphql_request_top_field_counts | Object | GraphQL APIs only. The maximum number of times that a query can retrieve each field. This
number is equal to the number of times that the resolver is required to run. This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change. |
| graphql_request_top_type_counts | Object | GraphQL APIs only. The maximum number of times that a query can retrieve an object of each
type. This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change. |
| graphql_request_type_cost | Number | GraphQL APIs only. The maximum cost of all types retrieved in the query. The cost of each type is configured in the schema. |
| graphql_response_field_cost | Number | GraphQL APIs only. The cost of all fields accessed in the query. The cost of each field access is configured in the schema. |
| graphql_response_max_nesting | Number | GraphQL APIs only. The nesting depth found in the query by the assembly validate action. The schema configuration is used to determine which types are considered nested, so this value might be less than the nesting depth found by the assembly parse action. |
| graphql_response_top_field_counts | Object | GraphQL APIs only. The number of times that each field was retrieved by the query. This
number is equal to the number of times that the resolver is required to run. This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change. |
| graphql_response_top_type_counts | Object | GraphQL APIs only. The number of times that an object of each type was retrieved by the
query. This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change. |
| graphql_response_type_cost | Number | GraphQL APIs only. The cost of all types that were retrieved in the query. The cost of each type is configured in the schema. |
| headers.field_name | String | Internal information that is related to analytics ingestion.
headers.field_name is not related to the API call or its response, see
request_http_headers for that information. |
| host | String | The hostname or IP address of the ingestion node that received the API event. |
| http_user_agent | String | The value of the User Agent header on the inbound request. |
| immediate_client_ip | String | The client IP address that is directly in front of the gateway. Usually
immediate_client_ip is the IP of a load balancer. |
| latency_info.started | Number | The time delay (in milliseconds) between when the request was received and when the gateway started the corresponding task. Starting a task comprises multiple steps to prepare for executing an API; for example, completing the TCP/TLS handshake, verifying an app's client ID and secret, and matching the request URI to a catalog, API, and Plan. When the gateway receives a request, the "Start" duration is set to 0. The duration of each step within the Start task is then added up, and the total represents the duration of the Start task. |
| latency_info.task | String | The API transaction that was processed. |
| log_policy | String | The defined logging policy. Values include none, event, headers, and payload. |
| method | String | The HTTP method used in the request. For example, GET, POST. |
| monitor_attribute | String | The custom attribute that is used for API monitoring. |
| opentracing_info | Object | The distributed tracing data for the request. |
| operation_path | String | The specific operation path within the API. |
| org_id | String | The identifier for the provider organization that owns the API and associated Products. |
| org_name | String | The name of the provider organization that owns the API and associated Products. |
| path | String | The full path of the API request. |
| path_id | String | The Identifier for the API path that is accessed. |
| plan_id | String | The Plan identifier. |
| plan_name | String | The name of the Plan. Note: The property is set to
undefined when a client ID
is not used or is invalid on the API. The gateway needs a client id to determine which app was
invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the
product that contains the API. Without a client ID, the gateway is unable to determine what plan,
product, or app was invoked because a single API can belong to multiple products (each of which have
multiple plans and apps that are subscribed to those plans with client IDs). |
| plan_version | String | The version number of the Plan. |
| product_id | String | The Identifier of the product that is associated with the API. |
| product_name | String | The Product name. Note: The property is set to
undefined when a client ID is
not used or is invalid on the API. The gateway needs a client ID to determine which app was invoking
the API. From this app, the gateway can determine what plan the app is subscribed to on the product
that contains the API. Without a client ID, the gateway is unable to determine what plan, product,
or app wasinvoked because a single API can belong to multiple products (each of which have multiple
plans and apps that are subscribed to those plans with client IDs). |
| product_title | String | The title of the Product. |
| product_version | String | The version number of the Product. |
| query_string | String | The URL query string value on the inbound request. |
| rate_limit | String | The maximum number of requests an application is allowed to make to the API during a specified time window. |
| rate_limit.count | Number | The number of API calls remaining in the specified rate limit time window. |
| rate_limit.interval | Number | The total time window during which a certain number of API calls are allowed. |
| rate_limit.limit | Number | The maximum number of requests an application is allowed to make to the API during a specified time window. |
| rate_limit.period | Number | The time window that is used to set a rate limit for API calls. |
| rate_limit.reject | String | An indication of whether calls that exceed the specified rate limit are rejected. If true, the API call is rejected with a 429 status code. If false, a record is created in the Activity log. |
| rate_limit.shared | String | An indication of whether the rate limit is shared at a Plan level by all operations, or whether a rate limit is specified on indivIDual operations. |
| rate_limit.unit | Number | The time unit used for calculating the rate limit. Note: Allowed values are second, minute,
hour, day, and week
|
| request_body | String | The body of the inbound request. |
| request_http_headers.field_name | String | A component of the HTTP header section of the inbound request; for example, the acceptable
encodings, the identification string for the user agent, or the proxies through which the request
was sent. Note: The following types of headers are considered sensitive and do not show in analytics
data for security reasons:
|
| request_method | String | The method of the inbound request. |
| request_protocol | String | The protocol of the inbound request. |
| resource | String | The name of the operation. |
| resource_id | String | The operation identifier. |
| resource_path | String | The operation path. |
| response_body | String | The body of the outbound response. |
| response_http_headers.field_name | String | A component of the HTTP header section of the outbound response; for example, the MIME type of the content or the data and time when the message was sent. |
| rule_name | String | The name of the rule that is applied to the request. |
| scope | String | Not used for DataPower® API Gateway or DataPower Gateway. |
| space_id | String | The Identifier of the space under which the API call was made. |
| space_name | String | The name of the space. |
| status_code | String | The status code set on the outbound response. |
| time_to_serve_request | Number | The time elapsed (in milliseconds) from when the gateway received the request to when it sent a response. |
| transaction_id | String | The identifier for the API transaction. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varservicetransaction-id-servicevarstransactionid. |
| uri_path | String | The URI path on the inbound request. |
| user_agent | Object | The parsed contents of the http_user_agent field, which contains information
about the user that made the API call. |
| user_agent.device | String | Device name. |
| user_agent.major | String | User agent major version number. |
| user_agent.minor | String | User agent minor version number. |
| user_agent.name | String | User agent name. |
| user_agent.os_full | String | Detected operating system full name. |
| user_agent.os_major | String | Detected operating system major version number. |
| user_agent.os_minor | String | Detected operating system minor version number. |
| user_agent.os_name | String | Detected operating system name. |
| user_agent.os_patch | String | Detected operating system patch version. |
| user_agent.os_version | String | Detected operating system version. |
| user_agent.patch | String | User agent patch version. |
| user_agent.version | String | Detected user agent version. |
| websocket_message_type | String | The type of WebSocket message. |
| websocket_origin | String | The origin header of the WebSocket connection. |