openapi: 3.2.0 info: title: v1 Rate Limit Rules API version: 1.0.0 description: 'The Rate Limit Rules API provides information about rate limit rules that are actively being enforced for your organization.' servers: - url: Use API Lookup for a base URL security: - token: [] - apiKey: [] tags: - name: Rate Limit Rules description: Access and manage rate limit rules for API endpoints on the platform paths: /identities/me/rules: get: summary: Get list of rate limit rules for the caller operationId: Rate Limit Rules API v1 getRateLimitRulesMe description: Get the list of rate limit rules that are actively enforced for the calling identity. tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/endpointIdRules' - $ref: '#/components/parameters/url' - $ref: '#/components/parameters/projectHrn' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/RulePageWithToken' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /identities/default/rules: get: summary: Get list of rate limit rules for the caller's realm operationId: Rate Limit Rules API v1 getRateLimitRulesDefault description: Get the list of rate limit rules that are actively enforced for any generic identity from the calling identity's realm whose rules are not overridden by custom rules or a custom tier. tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/endpointIdRules' - $ref: '#/components/parameters/url' - $ref: '#/components/parameters/projectHrn' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/RulePageWithToken' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /identities/{identityHrn}/rules: get: summary: Get list of rate limit rules for an identity operationId: Rate Limit Rules API v1 getRateLimitRulesIdentity description: 'Get the list of rate limit rules that are actively enforced for the given identity. Access Control: * The calling principal must have either **"readRateLimitRules"** action permission for the resource **"{identityHrn}"** in the **"iam-config"** service or **"manage"** action permission for the resource **"{identityHrn}"** in the **"account"** service. * The calling principal MUST NOT include a project scope.' tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/identityHrn' - $ref: '#/components/parameters/endpointIdRules' - $ref: '#/components/parameters/url' - $ref: '#/components/parameters/projectHrn' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/RulePageWithToken' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /identities/me/rules/{ruleHrn}: get: summary: Get rate limit rule for the caller operationId: Rate Limit Rules API v1 getRateLimitRuleCaller description: Get a single rate limit rule that is actively enforced for the calling identity. tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/ruleHrn' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Rule' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /identities/default/rules/{ruleHrn}: get: summary: Get rate limit rule for the caller's realm operationId: Rate Limit Rules API v1 getRateLimitRuleDefault description: Get a single rate limit rule that is actively enforced for any generic identity from the calling identity's realm whose rules are not overridden by custom rules or a custom tier. tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/ruleHrn' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Rule' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /identities/{identityHrn}/rules/{ruleHrn}: get: summary: Get rate limit rule for an identity operationId: Rate Limit Rules API v1 getRateLimitRuleIdentity description: 'Get a single rate limit rule that is actively enforced for the given identity. Access Control: * The calling principal must have either **"readRateLimitRules"** action permission for the resource **"{identityHrn}"** in the **"iam-config"** service or **"manage"** action permission for the resource **"{identityHrn}"** in the **"account"** service. * The calling principal MUST NOT include a project scope.' tags: - Rate Limit Rules parameters: - $ref: '#/components/parameters/identityHrn' - $ref: '#/components/parameters/ruleHrn' - $ref: '#/components/parameters/xRequestId' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/Rule' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: headers: X-Correlation-ID: description: 'Auto-generated ID, which uniquely identifies the request, available in the response. When contacting support with an inquiry regarding a specific request, provide the value of this header which will help troubleshooting the issue. ' schema: type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 X-Request-ID: description: 'User-provided token that can be used to trace a request or a group of requests sent to the service. ' schema: type: string parameters: identityHrn: name: identityHrn in: path description: 'Only include rules that apply to API calls from the specified identity. Values supported include a specific *appHrn* or a specific *userHrn*. ' required: true example: hrn:here:account::olp-here:app/Gtujkja8498vmk90 schema: type: string endpointIdRules: name: endpointId in: query description: Only include rules that apply to API calls to the specified endpoint. example: search-geocode schema: type: string url: name: url in: query description: Only include rules that apply to API calls to the specified URL. example: https://geocode.search.hereapi.com/v1/geocode?q=berlin schema: type: string limit: name: limit in: query description: Number of results to be returned. Values between 1 and 100 schema: type: integer projectHrn: name: projectHrn in: query description: Only include rules that apply to API calls from the specified project. example: hrn:here:authorization::olp-here:project/my-project-0000 schema: type: string xRequestId: name: X-Request-ID in: header description: User-provided token that can be used to trace a request or a group of requests sent to the service. schema: type: string ruleHrn: name: ruleHrn in: path description: HRN identifying the rate limit rule required: true example: hrn:here:iam::olp-here:ratelimit/freemium-policy-rate-limit-rule schema: type: string pageToken: name: pageToken schema: type: string in: query description: The cursor for pagination. Present only if there is an additional page of data to view. example: KuMvTQrdHVVKuMDDdcIvTQrdci1FWdcIHVVci1FW schemas: RuleSchemaVersion1: type: object required: - id - metric - requestMatchingCriteria - groupingMask properties: alwaysMatch: type: boolean description: A boolean that indicates if this rate limit rule should be enforced even if another rate limit rule also matches default: true metric: type: string description: Defines the unit to be rate limited. The bytesIn and bytesInPerRequest is the POST/PUT request Content-Length value. If rate limiting is enforced for these metrics 413 and 402 HTTP status codes are used respectively for the bytesIn and bytesInPerRequest metrics, instead of 429. Also the rate for bytesInPerRequest should be set using localRate. The usage-metric is applicable for custom metrics if a custom request auth pre-processor is used and that retuns a X-HERE-RateLimit-Usage HTTP header with the numerical increment. enum: - apiCalls - bytesIn - bytesInPerRequest groupingMask: type: array description: "Defines which values from the request that will be used to create the \\\"bucket key\\\" for this request.\nThis key determines which rate limiting bucket the request is counted against.\nThe mask is a list of field names indicating the fields that will be part of the key. The \\\"resourceHrn\\\" field includes a value, \nwhich is the requested resource name and not the potential wild card from the rule. For path-grouping the \\\"path\\\" indicates \nthe use of the original request path without query parameters and \\\"pathFromRule\\\" does grouping using the potential wild-card \nversion of the path in rule matching criteria. The \\\"identityHrn\\\" is a generic identity which depending on the claims can be \nbased on combination of \\\"rlm\\\" and one of \\\"aid\\\" app id, \\\"sub\\\" user id, or \\\"did\\\" device id claims. The \\\"action\\\" is \noptionally present and used to match with the serviceApiHandler action for this particular request. The \\\"tokenHrn\\\" is \noptionally present and constructed from combination realm \\\"rlm\\\" and JWT Token \\\"jti\\\" claims to uniquely distinguish a token. \nNote that this is currently applicable for third party tokens using shared application id but unique jti to mask the actual client identity.\n" items: type: string enum: - realmHrn - appHrn - projectHrn - endpointId - resourceHrn - path - pathFromRule - method - action - identityHrn - tokenHrn requestMatchingCriteria: $ref: '#/components/schemas/RequestMatchingCriteria' baseRate: $ref: '#/components/schemas/RateLimitValue' overwriteControl: type: string description: The "overwriteControl" is used to control how the overlapping rules are selected for the most specific one. The "byMatchingCriteria", which is default, means that only the matching criteria are considered during rule selection, and groupingMask has to be same for overwritten rules. The "byMatchingCriteriaAndGroupingMask" means that both the matching criteria and the grouping mask are considered during rule selection. enum: - byMatchingCriteria - byMatchingCriteriaAndGroupingMask ErrorDetail: type: object properties: title: type: string description: Error message example: Invalid size value source: type: string description: Reference to JSON path example: $.data.attributes[0].size message: type: string description: Detailed error message example: Size must be between 3 and 64 messageTemplate: type: string description: Optional error template example: validation.constraint.between messagePlaceholders: type: object additionalProperties: {} example: field: size min: 3 max: 64 ErrorResponse: type: object required: - title - status - code - cause - action - errorId - correlationId properties: title: description: Error title type: string example: Input data failed validation errorId: type: string example: ERROR-9d862c5a-4cfd-4780-8be4-2728b42849e1 description: Unique id for the error. This is searchable from HERE Account logs. status: description: HTTP Status Code type: integer example: 400 code: description: Service specific error code type: string example: E124101 cause: description: The cause of the error type: string example: The input data in question does not meet validation rules action: description: Actionable instructions for the API consumer type: string example: Correct input data and retry request correlationId: description: Trace ID associated with this request, for future use type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 details: type: array description: Collection of error details items: $ref: '#/components/schemas/ErrorDetail' AuthErrorResponse: type: object required: - error - error_description properties: error: type: string description: Error title error_description: type: string description: Error description RateLimitValue: type: object description: 'The rate limit value defined in context of the metric selected for the rule. ' required: - period - periodValue - value properties: period: type: string description: The time value unit to be used for periodValue example: minutes enum: - seconds - minutes - hours - days periodValue: type: integer description: The value of the time period based on unit defined in period example: 15 value: type: integer description: The value of the rate limit to be applied to the metric in the time window determined by periodValue example: 10000 Rule: type: object description: The rate limit data model separates the notion of applicability from grouping. Thus, a rate limiting rule can define the universe of requests to which it is applied, and can then separately define the way in which those requests will be grouped. For example, a rule could define a rate limit for all requests from clients in a certain realm, but group those requests by appId. A separate different rule could apply to the same realm, but group all the request from that realm together into a single bucket. required: - id - schemaVersion - rule properties: id: type: string description: User defined id for the rule example: freemium-policy-rate-limit-rule pattern: ^[a-z0-9-_]{6,32}$ hrn: type: string readOnly: true description: Hrn for the rate limiting rule example: hrn:here:iam::olp-here:ratelimit/freemium-policy-rate-limit-rule description: type: string description: Summary of the rule definition rule: $ref: '#/components/schemas/RuleSchemaVersion1' PageWithToken: type: object properties: total: example: 10 type: integer description: Total number of items pageToken: example: 7afd7f8e94eb4844ba45 type: string description: The pageToken used to retrieve the next page of items. Present only if there is an additional page of items to view. count: example: 2 type: integer description: Count of items returned in this query limit: example: 5 type: integer description: Maximum number of items as specified in request RequestMatchingCriteria: type: object description: The criteria is used to match a rule applies to the incoming request. properties: tier: type: integer description: Tier id assigned to the principal in the request example: 1 realmHrn: type: string description: HRN for the realm example: hrn:here:account::olp-here:realm/olp-here appHrn: type: string description: HRN for the app of the principal example: hrn:here:account::olp-here:app/Gtujkja8498vmk90 projectHrn: type: string description: Project scope value of the principal in the request example: hrn:here:authorization::olp-here:project/my-project-0000 endpointId: type: string description: The id of the endpoint being accessed in the request example: search-geocode path: type: string description: a path, which can be prefix or can begin or end in a wildcard (e.g. "/foo/bar/*"). example: /v1/geocode method: type: string example: GET description: HTTP method to be matched against the incoming request. resourceHrn: type: string description: a resource name/value pair. The name is matched against the named fields in the route of the request. A wildcard for the value indicates that the request will match if a field with the given name exists regardless of its value. Wildcard can be at the beginning or end of the resourceHrn. example: hrn:here:data::olp-here:my-catalog-1 action: type: string description: the action associated with the request example: geocode RulePageWithToken: allOf: - $ref: '#/components/schemas/PageWithToken' - type: object properties: items: type: array items: $ref: '#/components/schemas/Rule' responses: NotFound: description: The requested resource was not found, see error response for details headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: You do not have permission to perform this action headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' Unauthorized: description: Access is denied due to invalid credentials headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Request-ID: $ref: '#/components/headers/X-Request-ID' content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' securitySchemes: token: type: http scheme: bearer bearerFormat: JWT description: "A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request. \nFor more information on how to get a bearer token, see the\n[https://developer.here.com/documentation/identity-access-management/dev_guide/index.html](Identity & Access Management Guide).\n" apiKey: type: apiKey in: query name: apiKey description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [https://developer.here.com/documentation/identity-access-management/dev_guide/index.html](Identity & Access Management Guide). '