Tutorials: Quota service

The tutorials in this section show you how to perform various tasks within the quota service. The quota API is used to send a request, based on your previously configured rules, and then receive a response from the endpoint.

Endpoints

This tutorial uses org123456789 as the realmId.

Notes

Quota rules are applied per feature ID (HRN). See Concepts to view a list of commonly used feature IDs (HRNs).

For additional details regarding the following tutorials, see the quota-service OpenAPI specification.

Create, update, and delete quota rules

The tutorials in this section show you how to create, update, and delete quota rules.

Log search IO alert rule

Log search IO refers to the data transfer incurred when pipeline-generated log information is written and indexed for debugging purposes.

The following pertains to Log Search IO services:

  • Reported per unit in GB per hour and billed per month
  • Monthly prices represent usage over 720 hours
  • Calculation construct:
    • Total number of bytes written to the index
  • Costs are not incurred via API requests, but via optional developer code within a pipeline JAR file which writes to “std-out"

Request

       POST https://quota.bam.api.here.com/v1/realms/org123456789/rules
   {
     "name": "Example rule",
     "description": "Alert on Log search IO threshold 10Gi.",
     "queryConditions": [
       {
         "key": "featureId",
         "value": "hrn:here:portal::org123456789:logs"
       }
     ],
     "usageThresholdCondition": {
       "thresholdType": "percentage",
       "threshold": 70,
       "usageLimit": 70
     },
     "actionableEntity": {
       "entityId": "hrn:here:authorization::org123456789:project/my-project-0000",
       "entityType": "projectHrn"
     },
     "actions": [
       "alert"
     ],
     "timeRange": {
       "duration": "monthly"
     },
     "emailNotifications": [
       "example@here.com",
       "test@here.com"
     ]
   }

Response: HTTP 201 Created

   {
       "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
       "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
       "name": "Example rule",
       "description": "Alert on Log search IO threshold 10Gi.",
       "status": "active",
       "queryConditions": [
           {
               "key": "featureId",
               "value": "hrn:here:portal::org123456789:logs"
           }
       ],
       "usageThresholdCondition": {
           "thresholdType": "percentage",
           "threshold": 70,
           "usageLimit": 70
       },
       "actions": [
           "alert"
       ],
       "actionableEntity": {
           "entityType": "projectHrn",
           "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
       },
       "timeRange": {
           "duration": "monthly"
       },
       "ruleType": "alert",
       "emailNotifications": [
           "example@here.com",
           "test@here.com"
       ],
       "created": "2021-09-03T07:08:23Z",
       "modified": "2021-09-03T07:08:23Z",
       "createdBy": "dhIQFVejQgPkTXLn8CtH",
       "updatedBy": "dhIQFVejQgPkTXLn8CtH"
   }

Get all quota rules defined for your realm

As shown in the following, you can request the status for all of the quota rules provided by the quota service for your realm.

Requests

    Get rules for org123456789 realm (default pagination)
        GET https://quota.bam.api.here.com/v1/realms/org123456789/rules
    Get rules for org123456789 realm (with pagination paramaters)
        GET https://quota.bam.api.here.com/v1/realms/org123456789/rules?offset=2
        GET https://quota.bam.api.here.com/v1/realms/org123456789/rules?limit=30
        GET https://quota.bam.api.here.com/v1/realms/org123456789/rules?limit=75&offset=6
    Get rules for org123456789 realm with status=active
        GET https://quota.bam.api.here.com/v1/realms/org123456789/rules?status=active

Response

    HTTP 200 OK
{
    "total": 2,
    "limit": 100,
    "items": [
        {
            "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
            "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
            "name": "Example rule",
            "description": "Alert on Log search IO threshold 10Gi.",
            "status": "active",
            "queryConditions": [
                {
                    "key": "featureId",
                    "value": "hrn:here:portal::org123456789:logs"
                }
            ],
            "usageThresholdCondition": {
                "thresholdType": "percentage",
                "threshold": 70,
                "usageLimit": 70
            },
            "actions": [
                "alert"
            ],
            "actionableEntity": {
                "entityType": "projectHrn",
                "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
            },
            "timeRange": {
                "duration": "monthly"
            },
            "ruleType": "alert",
            "emailNotifications": [
                "example@here.com",
                "test@here.com"
            ],
            "created": "2021-09-03T07:08:23Z",
            "modified": "2021-09-03T07:08:23Z",
            "createdBy": "dhIQFVejQgPkTXLn8CtH",
            "updatedBy": "dhIQFVejQgPkTXLn8CtH"
        },
        {
            "ruleId": "CUSTOMER-QUOTA-8e95827b-141c-4848-8cd4-9f800ea84fc0",
            "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-8e95827b-141c-4848-8cd4-9f800ea84fc0",
            "name": "LogSearch IO Alert",
            "description": "Alert on Log search IO threshold over 10GiB.",
            "status": "active",
            "queryConditions": [
                {
                    "key": "featureId",
                    "value": "hrn:here:portal::org123456789:logs"
                }
            ],
            "usageThresholdCondition": {
                "thresholdType": "absolute",
                "threshold": 10
            },
            "actions": [
                "alert"
            ],
            "timeRange": {
                "duration": "daily"
            },
            "ruleType": "alert",
            "emailNotifications": [
                "example@here.com",
                "test@here.com"
            ],
            "created": "2021-08-20T11:26:50Z",
            "modified": "2021-08-20T11:26:50Z",
            "createdBy": "dhIQFVejQgPkTXLn8CtH",
            "updatedBy": "dhIQFVejQgPkTXLn8CtH"
        }
    ],
    "nextOffset": 0,
    "lastOffset": 0
}

This supports pagination (offset & limit) and allows filtering of results by multiple fields.

Get a quota rule defined for your realm by quota rule ID

As shown in the following, you can retrieve a specific quota rule for your realm by using a quota rule ID.

Request

    GET https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd

Response: HTTP 200 OK

{
    "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
    "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
    "name": "Example rule",
    "description": "Alert on Log search IO threshold 10Gi.",
    "status": "active",
    "queryConditions": [
        {
            "key": "featureId",
            "value": "hrn:here:portal::org123456789:logs"
        }
    ],
    "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 70,
        "usageLimit": 70
    },
    "actions": [
        "alert"
    ],
    "actionableEntity": {
        "entityType": "projectHrn",
        "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
    },
    "timeRange": {
        "duration": "monthly"
    },
    "ruleType": "alert",
    "emailNotifications": [
        "example@here.com",
        "test@here.com"
    ],
    "created": "2021-09-03T07:08:23Z",
    "modified": "2021-09-03T07:08:23Z",
    "createdBy": "dhIQFVejQgPkTXLn8CtH",
    "updatedBy": "dhIQFVejQgPkTXLn8CtH"
}

Update a quota rule defined for your realm by quota rule ID

As shown in the following, you can update a specific quota rule for your realm by using a quota rule ID.

Request

    PUT https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd
   {
     "name": "Example rule (updated)",
     "description": "Alert on Log search IO threshold 10Gi.",
     "actionableEntity": {
       "entityId": "hrn:here:authorization::org123456789:project/my-project-0000",
       "entityType": "projectHrn"
     },
     "actions": [
       "alert"
     ],
     "queryConditions": [
       {
         "key": "featureId",
         "value": "hrn:here:portal::org123456789:logs"
       }
     ],
     "usageThresholdCondition": {
       "thresholdType": "percentage",
       "threshold": 70,
       "usageLimit": 70
     },
     "timeRange": {
       "duration": "monthly"
     },
     "emailNotifications": [
       "example@here.com",
       "test@here.com"
     ],
   }

Response: HTTP 200 OK

   {
       "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
       "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
       "name": "Example rule (updated)",
       "description": "Alert on Log search IO threshold 10Gi.",
       "status": "active",
       "queryConditions": [
           {
               "key": "featureId",
               "value": "hrn:here:portal::org123456789:logs"
           }
       ],
       "usageThresholdCondition": {
           "thresholdType": "percentage",
           "threshold": 70,
           "usageLimit": 70
       },
       "actions": [
           "alert"
       ],
       "actionableEntity": {
           "entityType": "projectHrn",
           "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
       },
       "timeRange": {
           "duration": "monthly"
       },
       "ruleType": "alert",
       "emailNotifications": [
           "example@here.com",
           "test@here.com"
       ],
       "created": "2021-09-03T07:08:23Z",
       "modified": "2021-09-03T07:25:26Z",
       "createdBy": "dhIQFVejQgPkTXLn8CtH",
       "updatedBy": "dhIQFVejQgPkTXLn8CtH"
   }

Delete a quota rule defined for your realm by quota rule ID

As shown in the following, you can delete a specific quota rule for your realm by using a quota rule ID.

Request

    DELETE https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd

Response: HTTP 204 OK

Create app ID based quota rules

The following is a tutorial for app ID based rules. This rule is setup to suspend access to appId app1 for autosuggest API, if the app1 usage for autosuggest API crosses 1000 requests.

Request

       POST https://quota.bam.api.here.com/v1/realms/org123456789/rules
    {
      "name": "Example rule",
      "description": "Alert on Log search IO threshold 10Gi.",
      "queryConditions": [
        {
          "key": "featureId",
          "value": "hrn:here:service::org123456789:search-autosuggest-7"
        },
        {
          "key": "appId",
          "value": "app1"
        }
      ],
      "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 100,
        "usageLimit": 1000
      },
      "actionableEntity": {
        "entityId": "appId",
        "entityType": "app1"
      },
      "actions": [
        "alert",
        "suspend"
      ],
      "timeRange": {
        "duration": "monthly"
      },
      "emailNotifications": [
        "example@here.com",
        "test@here.com"
      ]
    }

Response: HTTP 201 Created

    {
      "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "name": "Example rule",
      "description": "Alert on Log search IO threshold 10Gi.",
      "queryConditions": [
        {
          "key": "featureId",
          "value": "hrn:here:service::org123456789:search-autosuggest-7"
        },
        {
          "key": "appId",
          "value": "app1"
        }
      ],
      "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 100,
        "usageLimit": 1000
      },
      "actionableEntity": {
        "entityId": "appId",
        "entityType": "app1"
      },
      "actions": [
        "alert",
        "suspend"
      ],
      "timeRange": {
        "duration": "monthly"
      },
      "emailNotifications": [
        "example@here.com",
        "test@here.com"
      ],
      "created": "2021-09-03T07:08:23Z",
      "modified": "2021-09-03T07:08:23Z",
      "createdBy": "dhIQFVejQgPkTXLn8CtH",
      "updatedBy": "dhIQFVejQgPkTXLn8CtH"
    }

Get quota violation rule defined by quota rule ID

As shown in the following, you can get a quota violation rule which was defined using the quota rule ID.

       GET https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd

`
    {
      "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "name": "Example rule",
      "description": "Alert on Log search IO threshold 10Gi.",
      "queryConditions": [
        {
          "key": "featureId",
          "value": "hrn:here:service::org123456789:search-autosuggest-7"
        },
        {
          "key": "appId",
          "value": "app1"
        }
      ],
      "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 100,
        "usageLimit": 1000
      },
      "actionableEntity": {
        "entityId": "appId",
        "entityType": "app1"
      },
      "actions": [
        "alert",
        "suspend"
      ],
      "timeRange": {
        "duration": "monthly"
      },
      "emailNotifications": [
        "example@here.com",
        "test@here.com"
      ],
      "created": "2021-09-03T07:08:23Z",
      "modified": "2021-09-03T07:08:23Z",
      "createdBy": "dhIQFVejQgPkTXLn8CtH",
      "updatedBy": "dhIQFVejQgPkTXLn8CtH"
    }

Update app id based quota rules

The following is a tutorial for app ID based rules. This rule is setup to suspend access to appId app1 for autosuggest API, if the app1 usage for autosuggest API crosses 1000 requests. Request

       PUT https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd
    {
      "name": "Auto suggest rule(updated)",
      "description": "Alert on Autosuggest threshold over 1000 request.",
      "queryConditions": [
        {
          "key": "featureId",
          "value": "hrn:here:service::org123456789:search-autosuggest-7"
        },
        {
          "key": "appId",
          "value": "app1"
        }
      ],
      "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 100,
        "usageLimit": 1000
      },
      "actionableEntity": {
        "entityId": "appId",
        "entityType": "app1"
      },
      "actions": [
        "alert",
        "suspend"
      ],
      "timeRange": {
        "duration": "monthly"
      },
      "emailNotifications": [
        "example@here.com",
        "test@here.com"
      ]
    }

Response: HTTP 200 updated

    {
      "ruleId": "CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd",
      "name": "Auto suggest rule(updated)",
      "description": "Alert on Autosuggest threshold over 1000 request.",
      "queryConditions": [
        {
          "key": "featureId",
          "value": "hrn:here:service::org123456789:search-autosuggest-7"
        },
        {
          "key": "appId",
          "value": "app1"
        }
      ],
      "usageThresholdCondition": {
        "thresholdType": "percentage",
        "threshold": 100,
        "usageLimit": 1000
      },
      "actionableEntity": {
        "entityId": "appId",
        "entityType": "app1"
      },
      "actions": [
        "alert",
        "suspend"
      ],
      "timeRange": {
        "duration": "monthly"
      },
      "emailNotifications": [
        "example@here.com",
        "test@here.com"
      ],
      "created": "2021-09-03T07:08:23Z",
      "modified": "2021-09-03T07:08:23Z",
      "createdBy": "dhIQFVejQgPkTXLn8CtH",
      "updatedBy": "dhIQFVejQgPkTXLn8CtH"
    }

Delete a quota rule defined for your realm by quota rule ID

As shown in the following, you can delete a specific quota rule for your realm by using a quota rule ID.

Request

    DELETE https://quota.bam.api.here.com/v1/realms/org123456789/rules/CUSTOMER-QUOTA-db8ac3fb-f560-482c-a1e5-1626d503e4cd

Response: HTTP 204 No Content

Get multiple quota violations for your realm

As shown in the following, you can retrieve multiple quota violations for your realm.

Requests

    Basic request with minimal necessary parameters
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03
    Requesting different page & limit
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03&limit=30
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03&offset=10
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03&limit=30&offset=10
    Filter by appId
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03&appId=app1
    Filter by projectHrn
        GET https://quota.bam.api.here.com/v1/realm/org123456789/violations?startDate=2021-02-01T05:10:23&endDate=2021-02-01T11:47:03&projectHrn=hrn%3Ahere%3Aauthorization%3A%3Aorg123456789%3Aproject%2Fmy-project-0000

Response: HTTP 200 OK

{
    "total": 1,
    "limit": 100,
    "items": [
        {
            "violationId": "QUOTA-VIOLATION-1152a465-7b67-33ac-883f-23310891a102",
            "violationDateTime": "2021-07-16T08:56:00",
            "startTime": "2021-07-13T08:56:00",
            "endTime": "2021-08-31T08:00:00",
            "usageDateTime": "2021-07-15T15:56:00",
            "actualUsage": 80,
            "threshold": 70,
            "ruleId": "CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
            "rule": {
                "ruleId": "CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
                "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
                "name": "Example rule",
                "description": "Alert on Log search IO threshold 10Gi.",
                "status": "active",
                "queryConditions": [
                    {
                        "key": "featureId",
                        "value": "hrn:here:portal::org123456789:logs"
                    }
                ],
                "usageThresholdCondition": {
                    "thresholdType": "percentage",
                    "threshold": 70,
                    "usageLimit": 70
                },
                "actions": [
                  "alert"
                ],
                "actionableEntity": {
                    "entityType": "projectHrn",
                    "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
                },
                "timeRange": {
                  "duration": "monthly"
                },
                "ruleType": "alert",
                "emailNotifications": [
                  "example@here.com",
                  "test@here.com"
                ],
                "created": "2021-07-13T08:56:00",
                "modified": "2021-07-13T08:56:00",
                "createdBy": "dhIQFVejQgPkTXLn8CtH",
                "updatedBy": "dhIQFVejQgPkTXLn8CtH"
            },
            "created": "2021-07-16T08:56:00",
            "modified": "2021-07-16T08:56:00",
            "createdBy": "dhIQFVejQgPkTXLn8CtH",
            "updatedBy": "dhIQFVejQgPkTXLn8CtH"
        }
    ],
    "nextOffset": 1,
    "lastOffset": 0
}

Get a quota violation for your realm by ID

As shown in the following, you can retrieve a specific quota violation in your realm.

Request

    GET https://quota.bam.api.here.com/v1/realm/org123456789/violations/QUOTA-VIOLATION-1152a465-7b67-33ac-883f-23310891a102

Response: HTTP 200 OK

{
    "violationId": "QUOTA-VIOLATION-1152a465-7b67-33ac-883f-23310891a102",
    "violationDateTime": "2021-07-16T08:56:00",
    "startTime": "2021-07-13T08:56:00",
    "endTime": "2021-08-31T08:00:00",
    "usageDateTime": "2021-07-15T15:56:00",
    "actualUsage": 80,
    "threshold": 70,
    "ruleId": "CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
    "rule": {
        "ruleId": "CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
        "hrn": "hrn:here:quota::org123456789:CUSTOMER-QUOTA-a303b771-4176-44bd-84f1-7bca57338a09",
        "name": "Example rule",
        "description": "Alert on Log search IO threshold 10Gi.",
        "status": "active",
        "queryConditions": [
            {
                "key": "featureId",
                "value": "hrn:here:portal::org123456789:logs"
            }
        ],
        "usageThresholdCondition": {
            "thresholdType": "percentage",
            "threshold": 70,
            "usageLimit": 70
        },
        "actions": [
          "alert"
        ],
        "actionableEntity": {
            "entityType": "projectHrn",
            "entityId": "hrn:here:authorization::org123456789:project/my-project-0000"
        },
        "timeRange": {
          "duration": "monthly"
        },
        "emailNotifications": [
          "example@here.com",
          "test@here.com"
        ],
        "created": "2021-07-13T08:56:00",
        "modified": "2021-07-13T08:56:00",
        "createdBy": "dhIQFVejQgPkTXLn8CtH",
        "updatedBy": "dhIQFVejQgPkTXLn8CtH"
    },
    "created": "2021-07-16T08:56:00",
    "modified": "2021-07-16T08:56:00",
    "createdBy": "dhIQFVejQgPkTXLn8CtH",
    "updatedBy": "dhIQFVejQgPkTXLn8CtH"
}

Delete quota violations for your realm

As shown in the following, you can delete specific quota violations from your realm. This API unblocks the access to the API for an app ID.

Requests

    Delete all violations for org123456789 realm
        DELETE https://quota.bam.api.here.com/v1/realm/org123456789/violations
    Delete violations with appId=app1 for org123456789 realm
        DELETE https://quota.bam.api.here.com/v1/realm/org123456789/violations?appId=app1
    Delete violations with projectHrn=hrn:here:authorization::org123456789:project/my-project-0000 for org123456789 realm
        DELETE https://quota.bam.api.here.com/v1/realm/org123456789/violations?projectHrn=hrn%3Ahere%3Aauthorization%3A%3Aorg123456789%3Aproject%2Fmy-project-0000
    Delete violation with violationId=QUOTA-VIOLATION-1152a465-7b67-33ac-883f-23310891a102 for org123456789 realm
        DELETE https://quota.bam.api.here.com/v1/realm/org123456789/violations?violationId=QUOTA-VIOLATION-1152a465-7b67-33ac-883f-23310891a102

Response

    HTTP 204 No content

Quota Rule Triggers

Once a quota rule is evaluated and an alert email is sent for a given month, the alert email does not get triggered again for the same month unless the quota rule usage threshold condition changes.

Quota Rule Suspend

When a quota rule with suspend action is triggered, access to the HERE service is blocked for the actionable entity (either realm, app or project).

If the timeRange for the quota rule is monthly, access is blocked until the end of the month. If the timeRange is daily, access is blocked until the end of day.

When the access is blocked and an entity tries to access HERE service, the HERE API throws an HTTP 402 error. Sample request and response to search autosuggest API.

Request

  GET https://search.hereapi.com/v1/autosuggest?q="Eismieze Berlin"&at=52.5308,13.3856

Response

 HTTP 402 Service usage limit was reached

results matching ""

    No results matching ""