HERE Rate Limit Rules API

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: RateLimitRulesAPIV1GetRateLimitRulesMe
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRulesMe
  /identities/default/rules:
    get:
      summary: Get list of rate limit rules for the caller's realm
      operationId: RateLimitRulesAPIV1GetRateLimitRulesDefault
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRulesDefault
  /identities/{identityHrn}/rules:
    get:
      summary: Get list of rate limit rules for an identity
      operationId: RateLimitRulesAPIV1GetRateLimitRulesIdentity
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRulesIdentity
  /identities/me/rules/{ruleHrn}:
    get:
      summary: Get rate limit rule for the caller
      operationId: RateLimitRulesAPIV1GetRateLimitRuleCaller
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRuleCaller
  /identities/default/rules/{ruleHrn}:
    get:
      summary: Get rate limit rule for the caller's realm
      operationId: RateLimitRulesAPIV1GetRateLimitRuleDefault
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRuleDefault
  /identities/{identityHrn}/rules/{ruleHrn}:
    get:
      summary: Get rate limit rule for an identity
      operationId: RateLimitRulesAPIV1GetRateLimitRuleIdentity
      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'
      x-operation-id-source: normalized
      x-operation-id-original: Rate Limit Rules API v1 getRateLimitRuleIdentity
components:
  schemas:
    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
    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
    RulePageWithToken:
      allOf:
      - $ref: '#/components/schemas/PageWithToken'
      - type: object
        properties:
          items:
            type: array
            items:
              $ref: '#/components/schemas/Rule'
    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
    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
    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
    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'
  parameters:
    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
    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
    endpointIdRules:
      name: endpointId
      in: query
      description: Only include rules that apply to API calls to the specified endpoint.
      example: search-geocode
      schema:
        type: string
    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
    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
    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
    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
    limit:
      name: limit
      in: query
      description: Number of results to be returned. Values between 1 and 100
      schema:
        type: integer
  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'
  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
  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).

        '