components:
  parameters:
    keyId:
      in: path
      name: keyId
      required: true
      schema:
        $ref: '#/components/schemas/Id'
    nextToken:
      in: query
      name: nextToken
      required: false
      schema:
        $ref: '#/components/schemas/NextToken'
    transactionId:
      in: path
      name: transactionId
      required: true
      schema:
        $ref: '#/components/schemas/Id'
  schemas:
    Id:
      maxLength: 64
      minLength: 1
      pattern: '[a-zA-Z0-9_-]+'
      type: string
    Key:
      properties:
        audiences:
          items:
            $ref: '#/components/schemas/Id'
          maxLength: 10
          minLength: 1
          type: array
        keyId:
          $ref: '#/components/schemas/Id'
        resources:
          items:
            $ref: '#/components/schemas/Resource'
          maxLength: 10
          minLength: 1
          type: array
      required:
        - keyId
        - resources
        - audiences
      type: object
    KeyCreate:
      properties:
        audiences:
          items:
            $ref: '#/components/schemas/Id'
          maxLength: 10
          minLength: 1
          type: array
        keyId:
          $ref: '#/components/schemas/Id'
        resources:
          items:
            $ref: '#/components/schemas/Resource'
          maxLength: 10
          minLength: 1
          type: array
      required:
        - resources
        - audiences
      type: object
    KeyUsage:
      properties:
        keyId:
          description: |
            The id of the key whose consumption is being metered.
          type: string
        resources:
          items:
            $ref: '#/components/schemas/ResourceUsage'
          type: array
      required:
        - keyId
        - resources
      type: object
    NextToken:
      maxLength: 4096
      pattern: ^[a-zA-Z0-9_-]+$
      type: string
    ResetBehavior:
      default: WIPE
      description: >-
        Whether to transfer or wipe the usage of a key dimension when the key is
        reset.
      enum:
        - WIPE
        - TRANSFER
      type: string
    ResetPendingEnum:
      default: FAIL
      enum:
        - FAIL
        - WIPE
        - TRANSFER
      type: string
    Resource:
      properties:
        accessUntilDate:
          description: |
            The deadline for using this resource, after
            which new transactions will be rejected.
          format: date-time
          type: string
        limit:
          description: |
            A numerical limit for this specific resource. 
            New transactions over this threshold will be rejected.
          type: number
        readOnly:
          default: false
          description: >
            This resource is managed by the subscription service and cannot be
            modified by the application. This applies to `LICENSED` resources
            where the subscription service measures the consumption.
          type: boolean
        resetBehavior:
          $ref: '#/components/schemas/ResetBehavior'
        resourceId:
          $ref: '#/components/schemas/Id'
        transactionLimits:
          properties:
            maximumQuantity:
              description: |
                The maximum quantity for a transaction.
              type: number
            minimumQuantity:
              default: 0
              description: >
                The minimum quantity for a transaction. Can be negative if
                transactions should be able to reduce the confirmed quantity on
                the resource. Transactions with negative quantity will not
                affect the pending quantity. A transaction that would cause the
                confirmed quantity to go negative will be rejected.
              type: number
          type: object
      required:
        - resourceId
      type: object
    ResourceUsage:
      properties:
        accessUntilDate:
          description: |
            The deadline for using this resource, after
            which new transactions will be rejected.
          format: date-time
          type: string
        confirmed:
          description: Total quantity of confirmed transactions incurred for this resource.
          type: number
        limit:
          description: |
            A numerical limit for this specific resource. 
            New transactions over this threshold will be rejected.
          type: number
        pending:
          description: Total quantity of pending transactions incurred for this resource.
          type: number
        readOnly:
          default: false
          description: >
            This resource is managed by the subscription service and cannot be
            modified by the application. This applies to `LICENSED` resources
            where the subscription service measures the consumption.
          type: boolean
        resetBehavior:
          $ref: '#/components/schemas/ResetBehavior'
        resourceId:
          $ref: '#/components/schemas/Id'
        transactionLimits:
          properties:
            maximumQuantity:
              description: |
                The maximum quantity for a transaction.
              type: number
            minimumQuantity:
              default: 0
              description: >
                The minimum quantity for a transaction. Can be negative if
                transactions should be able to reduce the confirmed quantity on
                the resource. Transactions with negative quantity will not
                affect the pending quantity. A transaction that would cause the
                confirmed quantity to go negative will be rejected.
              type: number
          type: object
      required:
        - resourceId
        - pending
        - confirmed
      type: object
    Transaction:
      properties:
        expirationDate:
          description: >
            The expiration date of a transaction. If not committed or rolled
            back, a

            transaction will expire and the quantity will be returned to the
            key.
          format: date-time
          type: string
        keyId:
          description: The id of the key who incurred the transaction.
          type: string
        quantity:
          description: The quantity consumed by the key in this transaction.
          type: number
        resourceId:
          description: |
            The id of a metered resource this key is allowed to access.
          type: string
        status:
          $ref: '#/components/schemas/TransactionStatusEnum'
        transactionId:
          description: The id associated with a particular transaction.
          type: string
      required:
        - transactionId
        - resourceId
        - keyId
        - quantity
        - expirationDate
        - status
      type: object
    TransactionStatusEnum:
      description: Indicates the status of a transaction.
      enum:
        - PENDING
        - CONFIRMED
        - CANCELED
        - EXPIRED
      type: string
    Transactions:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Transaction'
          type: array
        nextToken:
          $ref: '#/components/schemas/NextToken'
      required:
        - items
      type: object
  securitySchemes:
    ApplicationAuth:
      in: header
      name: Authorization
      type: apiKey
info:
  description: |
    The metering API enables you to track usage of specific `resources`
    by creating and managing `transactions`. Transactions are assigned 
    to keys, which can represent users, etc.
  title: Metering API
  version: 1.1.2
openapi: 3.0.3
paths:
  /keys:
    post:
      description: |
        Keys must be initialized before you can begin tracking their usage.
        You should specify accessible resources in `items`, along with any
        quantity limits or date cutoffs.

        The key  can only be reset or modified by the user that created it.
      operationId: createKey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyCreate'
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  keyId:
                    $ref: '#/components/schemas/Id'
                required:
                  - keyId
                type: object
          description: Key created.
        '400':
          description: Bad request
        '409':
          description: Key already exists.
      security:
        - ApplicationAuth: []
      summary: Initialize Key
      tags:
        - Keys
  /keys/{keyId}:
    get:
      description: Get resource usage data for a specific key.
      operationId: describeKey
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyUsage'
          description: The requested key's usage.
        '404':
          description: Key not found.
      security:
        - ApplicationAuth: []
      summary: Describe Key
      tags:
        - Keys
    parameters:
      - $ref: '#/components/parameters/keyId'
    patch:
      description: >
        Update a key's audience and resource lists. At least one of `audiences`
        or `resources` must be provided.
      operationId: updateKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                audiences:
                  description: >
                    If provided, overwrites the list of audiences allowed to
                    create transactions on this key.
                  items:
                    type: string
                  type: array
                resources:
                  description: >
                    Updates `limit` and `accessUntilDate` on specified
                    resources. 

                    If either is left `undefined` it will remove the respective 

                    value as long as the resourceId is passed. Every resourceId 

                    provided must already exist, but if a resourceId is not 

                    passed it will not be updated.
                  items:
                    $ref: '#/components/schemas/Resource'
                  type: array
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Key'
          description: Key updated. Returns new key.
        '404':
          description: Key not found.
      security:
        - ApplicationAuth: []
      summary: Update Key
      tags:
        - Keys
    put:
      description: >
        Reset the usage for all resources atomically. Returns the key's usage
        prior to being 

        reset - equivalent to `Describe Key` before a reset. The resetPending 

        attribute gives the user the option to either fail if there's a pending 

        txn, carry it over to the new key, or reset it to zero. Defaults to 

        'FAIL'. Resources that have the reset behavior set to TRANSFER will

        have their usage roll over.
      operationId: resetKey
      requestBody:
        content:
          application/json:
            schema:
              properties:
                resetPending:
                  $ref: '#/components/schemas/ResetPendingEnum'
                resources:
                  items:
                    $ref: '#/components/schemas/Resource'
                  type: array
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyUsage'
          description: Key reset. Returns prior usage.
        '400':
          description: Bad request.
        '404':
          description: Key not found.
      security:
        - ApplicationAuth: []
      summary: Reset Key
      tags:
        - Keys
  /keys/{keyId}/transactions:
    get:
      description: Get list of transactions for a specific key.
      operationId: listTransactions
      parameters:
        - in: query
          name: status
          required: true
          schema:
            description: >-
              Results only contain transactions with the specified status
              type(s).
            example: CANCELED,EXPIRED
            pattern: >-
              [PENDING|CONFIRMED|CANCELED|EXPIRED]([,PENDING|,CONFIRMED|,CANCELED|,EXPIRED]){0,3}
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions'
          description: >-
            A list of transactions belonging to the requested key. By default
            only `PENDING` transactions are shown.
        '404':
          description: Key not found.
      security:
        - ApplicationAuth: []
      summary: List Transactions
      tags:
        - Transactions
    parameters:
      - $ref: '#/components/parameters/keyId'
      - $ref: '#/components/parameters/nextToken'
  /transactions:
    post:
      description: >
        Create a new transaction. Quantity should be an upper bound if unknown,
        as 

        adjustments (via `PUT /transactions/transactionId`) can only decrease
        the quantity.

        Returns the `transactionId` which should be kept track of by your
        application

        in order to describe, confirm, update, or cancel the transaction.
      operationId: createTransaction
      requestBody:
        content:
          application/json:
            schema:
              properties:
                commit:
                  default: false
                  description: Immediately commit the transaction
                  type: boolean
                expiration:
                  default: 3600
                  description: Expiration of the transaction in seconds.
                  example: 120
                  maximum: 86400
                  minimum: 0
                  type: number
                keyId:
                  $ref: '#/components/schemas/Id'
                quantity:
                  description: |
                    An upper bound on the quantity consumed by the key.
                    This can be reduced via `PUT /transactions/{transactionId}`
                  type: number
                resourceId:
                  $ref: '#/components/schemas/Id'
              required:
                - keyId
                - resourceId
                - quantity
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  transactionId:
                    $ref: '#/components/schemas/Id'
                required:
                  - transactionId
                type: object
          description: Created successfully.
        '400':
          description: Bad request.
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      security:
        - ApplicationAuth: []
      summary: Create Transaction
      tags:
        - Transactions
  /transactions/{transactionId}:
    delete:
      description: Cancel a transaction.
      operationId: cancelTransaction
      responses:
        '200':
          description: Canceled.
        '404':
          description: Not Found.
      security:
        - ApplicationAuth: []
      summary: Cancel Transaction
      tags:
        - Transactions
    get:
      description: Get specific transaction details.
      operationId: describeTransaction
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
          description: The requested transaction.
        '401':
          description: Unauthorized
        '404':
          description: Not Found.
      security:
        - ApplicationAuth: []
      summary: Describe Transaction
      tags:
        - Transactions
    parameters:
      - $ref: '#/components/parameters/transactionId'
    post:
      description: Commit a transaction.
      operationId: commitTransaction
      responses:
        '200':
          description: Committed.
        '400':
          description: Bad request.
        '404':
          description: Not Found.
      security:
        - ApplicationAuth: []
      summary: Commit Transaction
      tags:
        - Transactions
    put:
      description: >
        Update transaction quantity to a reduced value. An increase isn't
        allowed as it 

        could conflict with limits (initial transaction quantities should be an
        upper 

        bound). Instead, a new transaction should be initiated.


        Transactions can only be updated by the user and application that
        created the transaction.
      operationId: updateTransaction
      requestBody:
        content:
          application/json:
            schema:
              properties:
                quantity:
                  description: The (reduced) quantity consumed.
                  type: number
              required:
                - quantity
              type: object
      responses:
        '200':
          description: Updated.
        '400':
          description: Bad request.
        '404':
          description: Not Found.
      security:
        - ApplicationAuth: []
      summary: Update Transaction
      tags:
        - Transactions
servers:
  - url: https://metering.emddigital.com/v1
