Nav

Using API Alerts

An API alert is an alarm that signals an API administrator or owner of one or more of the following conditions:

  • The API request violates a policy or service level access (SLA).

  • Requests received by the API exceed a given number within a period of time.

  • The API returns a specified HTTP error code.

  • The API response time exceeds a certain amount.

Runtime Manager alerts differ in nature from API alerts. Runtime Manager flags CPU usage, secure data gateway up/down, and deployment success/failure, to name a few. API alerts, on the other hand, relate to an API request or response.

Prerequisites for Adding and Viewing Alerts

You create and configure an API alert by adding alerts to an API version in API Manager.

To add alerts, you need to meet all of the following conditions:

  • You successfully completed an initial deployment of the API.

  • You are assigned one of the following roles:

    • API Versions Owner

    • API Creators

    • Organization Administrators

  • In the case of a policy alert, you applied a policy to the API version.

To view alerts, you need to meet one of the following conditions:

  • You are assigned to the Organization Administrators role for the organization of the target API.

    As an organization administrator, you can see alerts related to APIs within your organization only.

  • You own the target API version.

    As an API version owner, you can see only the alerts added to a version that you own.

A user other than an organization administrator or API owner, for example a member of the Portals Viewer role who requests and receives access to an API from an API portal, cannot see alerts.

Adding Alerts

You can add alerts for a deployed API version from the API Administration or API Version details page. The Alerts tab appears on the API version details page after you deploy the API.

To add an alert:

  1. On the API Administration page, select the API by clicking in the area of the version name. On the hamburger menu, select the Alerts menu item.

    API Administration page

    using-api-alerts-50f5f

    When you select the Alerts item from the hamburger menu, the Alerts page appears, listing any previously added alerts.

    using-api-alerts-4b748
  2. Click Add alert.

    The Create alert page appears. You can add several types of alerts:

    • Policy violation

      An infraction of one or more policies that govern the API occurs.

    • Request Count

      Users request access to the API more times than allowed in a specified period of time.

    • Request Code

      The API returns one of these HTTP codes upon receiving a request: 400, 401, 403, 404, 408, 500, 502, or 503

    • Response Time

      The response time of the API exceeds a specified period.

  3. Select alert options, and click Submit.

To add an alert from the API version details page:

  1. Deploy the API version if it is not already deployed.

  2. Select the Alerts tab.

  3. Do steps 2-3, described in the previous procedure.

Request Count Alert Example

A request count alert condition is similar to a policy alert that uses the rate limiting policy.

To add a request count alert:

  1. In API Manager, access API Designer.

    • Download the RAML for creating an API that consumes a web service JSONPlaceholder.

    • Copy/paste the RAML into API Designer.

  2. On the API version details page, configure the endpoint, and deploy the API. For example, deploy the API to CloudHub.

  3. On the API version details page of the deployed API, after the API Status indicator shows that the API is deployed, go to the Alerts tab.

  4. Click Add alert, and set the alert options:

    • Name: Type an alert name, for example red-alert.

    • Enabled: Accept the default, Enabled.

    • Severity: Accept the default, Critical.

    • Api: Select the name of an API. For example, jsonplaceholderapi.

    • Api verison: Select a version. For example, 1.0.development.

    • Alert type: Select Request Count.

    • When number of occurrences are: Select Greater.

    • than: Select 1.

    • For at least: Select 1.

      Valid entries are in the range 1 - 999999999. These time intervals specified are implemented as sliding windows, not absolute minute boundaries, to prevent problems caused by data bursts.

    • Recipients: Select the names of users in your business group, or type the email addresses, of users who will receive notification when the alert fires. Press RETURN.

      using-api-alerts-37b31
  5. Click Submit.

To test the example request count alert:

  1. On the API version details page, in Status, click the CloudHub URL for the API.

    Resource not found appears.

  2. Add /users to the URL, and press Return.

    The list of users appears.

  3. Reload the page two more times.

    API calls exceeded appears if you performed the last three steps within the 1 minute period. Any additional page reload operations within the 1 minute period have no effect.

Selected users receive email notifications that requests exceeded the alert threshold and that the alert was resolved.

Alert Notification

When the alert fires, API Manager sends email notifications to you, and to others if configured.

When you set an alert, you select users in your Business Group who can receive email notifications about the alert. The notification includes information about events that trigger the alert as specified by the level of severity. Users receive two emails:

  • One email describes the alert. For example:

    Your API Version, jsonplaceholderapi - 1.0.development, has received greater than 1 requests within 1 consecutive periods of 1 minutes.

  • Another email notifies you when the alert is resolved.

    Your API Version, jsonplaceholderapi - 1.0.development, is no longer in an alert state. The number of policy violations was not greater than 1 in the last 1 consecutive periods of 1 minutes.

After an alert fires, and API Manager sends the first set of two notification emails, and stops listening for alerts until the next alert period begins. This technique prevents repetitive notification emails.

Viewing and Deleting API Alerts

In the Organization Administrators role, you can view a list of alerts from the API Administration page or API version details page. In the API Verisons Owner, API Creators, or Organization Administrators roles, you can use the Alerts tab on the API version details page to view information about your API.

To view and delete alerts from the API Administration page:

  1. Use the hamburger menu on the API Administration page to select the Alerts menu item.

    The Alerts page appears.

  2. Select one alert in the list.

    using-api-alerts-ca625

    Details about the alert options appear in the pane to the right.

  3. Delete the alert using the icon in the pane.

To view and delete alerts from the API version details page:

  1. On the alerts tab, click Edit to view alert option details.

  2. To cancel the Editing operation, click the version name in the breadcrumb.

  3. On the alerts tab, click Delete to delete the alert.

Editing API Alerts

You can edit alerts from the API Administration by clicking the name of the alert in the list of alerts. You can also edit alerts from the API version details page as follows:

  1. On the API version details page, on the Alerts tab, click Edit to edit alert options.

    using-api-alerts-aef33

    The Edit Alert page appears.

  2. Change options.

  3. Click Submit.

To cancel editing an alert, click the version name in the breadcrumb.

Disabling and Enabling Alerts

By default, after setting an alert, the alert is enabled. You can enable multiple alerts. You can disable the alert without deleting it, and trigger the alert later.

To disable the alert:

  1. On the API version details page, on the Alerts tab, click Edit to edit alert options.

  2. Click Disabled on the Create Alert or Edit Alert page.