---
openapi: 3.0.0

info:
  title: "Subscription change history"
  version: 1.0.2
  description: "Subscription change events query"
  x-api-id: "63664bd7-560a-463c-baf6-a91c215a3071"
  x-audience: "external-partner"

servers:
  - url: https://iot-api.aeris.com/iot/api/subscriptions/changes
    description: API server

paths:

  "/requests":
    post:
      summary: "Request subscription change history"
      description: >
        Create a request to get subscription change history for a batch of
        subscriptions
      operationId: "create-subscriptions-history-request"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeHistoryRequest'
      responses:
        "201":
          description: "Created, Location header will contain the created url"
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
        "429":
          $ref: '#/components/responses/Response_429'
        default:
          description: >
            error occurred - see status code and problem object for more
            information.
          content:
            "application/problem+json":
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - Oauth2_auth:
            - "subscription-history.read"

  "/requests/{request-id}":
    get:
      summary: "Get results for subscription change history request"
      description: "Get results for subscription change history request"
      operationId: "get-subscriptions-history"
      parameters:
        - name: request-id
          in: path
          schema:
            type: string
            example: "ABC123321"
          required: true
        - name: page
          in: query
          required: false
          schema:
            type: string
            example: "RW5jb2RlZCBrZXkg"
      responses:
        "200":
          description: >
            OK.
          allOf:
            - $ref: '#/components/responses/RateLimitedResponse'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChangeHistoryResponse"
        "429":
          $ref: '#/components/responses/Response_429'
        default:
          description: >
            error occurred - see status code and problem object for more
            information.
          content:
            "application/problem+json":
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - Oauth2_auth:
            - "subscription-history.read"

components:
  headers:
    Content-Type:
      description: Handle Content-Type
      schema:
        type: string
    X-RateLimit-Limit-Second:
      description: The maximum number of requests allowed in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Limit-Minute:
      description: The maximum number of requests allowed in a minute.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Second:
      description: The number of requests remaining in a second.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining-Minute:
      description: The number of requests remaining in a minute.
      schema:
        type: integer
        format: int32
  securitySchemes:
    Oauth2_auth:
      flows:
        password:
          tokenUrl: https://iot-api.aeris.com/iot/api/auth/token
          scopes:
            subscription-history.read: access subscription history
      type: oauth2
  responses:
    RateLimitedResponse:
      headers:
        X-RateLimit-Limit-Second:
          $ref: '#/components/headers/X-RateLimit-Limit-Second'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/X-RateLimit-Limit-Minute'
        X-RateLimit-Remaining-Second:
          $ref: '#/components/headers/X-RateLimit-Remaining-Second'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/X-RateLimit-Remaining-Minute'
        Content-Type:
          $ref: '#/components/headers/Content-Type'
    Response_429:
      description: "Too Many Requests"
      allOf:
        - $ref: '#/components/responses/RateLimitedResponse'
      content:
            "application/problem+json":
              schema:
                $ref: '#/components/schemas/Problem'

  schemas:
    IdType:
      type: "string"
      description: "Type of identifier used for identifier or identifier-range"
      x-extensible-enum:
        - imsi
        - subscription-package
      example: imsi

    IdentifierRangeType:
      type: "object"
      properties:
        start:
          description: "Start of range, inclusive"
          type: "string"
          example: "123456789000000"
        end:
          description: "End of range, inclusive"
          type: "string"
          example: "123456789099999"

    SubscriptionOperation:
      type: "string"
      description: Type of change
      example: "CHANGE_SUBSCRIPTIONSTATE"
      x-extensible-enum:
        - CESS
        - CHANGE_ALTROAMINGPROVIDER
        - CHANGE_SP_EUICC
        - CHANGE_SUBSCRIPTIONIP
        - CHANGE_SUBSCRIPTIONLABEL
        - CHANGE_SUBSCRIPTION_NOTE
        - CHANGE_SUBSCRIPTIONOWNER
        - CHANGE_SUBSCRIPTIONOWNER_EUICC
        - CHANGE_SUBSCRIPTIONPACKAGE
        - CHANGE_SUBSCRIPTIONREGION
        - CHANGE_SUBSCRIPTIONSTATE
        - CHANGE_SUBSCRIPTIONSTATE_EUICC
        - CREATE_SUBSCRIPTION
        - CREATE_SUBSCRIPTION_EUICC
        - INDIVIDUAL_APN_UPDATE
        - LOCK_SUBSCRIPTIONSTATE
        - PBR_EXIT
        - PCL_LIMIT_100_EXCEEDED
        - REASSIGN_MSISDN
        - THROTTLE_IMSI
        - TRIGGER_ACTION
        - UNLOCK_SUBSCRIPTIONSTATE
        - UPDATE_IMEI
        - UPDATE_ASSIGNED_IMEI

    ChangeHistoryRequest:
      type: "object"
      required:
        - identifier-type
        - since
      properties:
        identifier_type:
          $ref: "#/components/schemas/IdType"
        identifiers:
          description: >
            List of identifiers to query.  Either this or identifier range is
            required.  Max number of items allowed depends on identifier-type.
            Group identifiers, like subscription-package only one is allowed.
            For subscription identifiers max 1000 is allowed.
          type: "array"
          items:
            type: "string"
          example: ["subscriptionPackageId"]
        identifier_ranges:
          description: >
            Subscription identifier range.  Only one range is allowed per
            request.  Max range size vary with identifier type used.
            For imsi 100k is allowed and for other identifiers 1k is allowed.
          type: "array"
          items:
            $ref: "#/components/schemas/IdentifierRangeType"
        since:
          description: >
            Start date for query period, inclusive.  Earliest 3 months before
            current date.
          type: "string"
          format: date-time
          example: "2021-02-01T00:00:00Z"
        until:
          description: >
            End date for query period, exclusive.  Default 24h after the since
            property. Must be after since value.
          type: "string"
          format: date-time
          example: "2021-02-02T00:00:00Z"
        changes:
          description: >
            Change operations to include, comma separated values.  Default
            everything.
          type: "array"
          items:
            $ref: "#/components/schemas/SubscriptionOperation"
        page_limit:
          description: >
            Limit max returned items per result page, default 10000.
            Max 10000.
          type: "integer"
          example: 10000

    ChangeHistoryResponse:
      type: "object"
      properties:
        changes:
          description: >
            Array of changes.  Even if array is empty or below page limit,
            there can be more changes in the next page.
          type: "array"
          items:
            $ref: "#/components/schemas/SubscriptionChange"
        next:
          type: "string"
          description: >
            Link to next page result.  There can be next page even if changes
            in this response is under page limit or empty.
          example: "https://iot-api.aeris.com/iot/api/subscriptions\
            /changes/requests/ABC123321?page=RW5jb2RlZCBrZXkg"

    SubscriptionChange:
      type: "object"
      properties:
        occured_at:
          description: Date for the change
          type: "string"
          format: date-time
          example: "2021-02-02T12:45:56.789Z"
        imsi:
          description: Imsi for subscription
          type: "string"
        change:
          $ref: "#/components/schemas/SubscriptionOperation"
        initiated_by:
          type: "string"
          description: Change initiated by id
          example: accountid@example.org
        subscription_request_id:
          type: "string"
          description: Subscription request identifier for the change
          example: REQ123
        new_values:
          $ref: "#/components/schemas/Values"

    Values:
      type: "object"
      description: "New value for a change.  Only relevant field returned."
      properties:
        subscription_state:
          type: string
          example: active
          x-extensible-enum:
            - NEW
            - ACTIVE
            - PAUSE
            - DEACTIVATED
            - TERMINATED
            - REMOVED
            - OPERATOR-BLOCKED
            - TERMINATED-PENDING
            - ACTIVE-NO-BILLING
            - DEACTIVATED-NO-BILLING
        subscription_package:
          type: string
          example: sp-1
        label:
          type: string
          example: label-2
        detected_imei:
          type: string
          example: 00000123456789
        assigned_imei:
          type: string
          example: 00000123456789

    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When
            dereferenced,it SHOULD provide human-readable documentation
            for the problem type (e.g., using HTML).
        title:
          type: string
          description: |
            A short summary of the problem type in english and readable for
            engineers.
          example: 'Bad request'
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 400
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
          example: 'Uknown identifier_type'
        instance:
          type: string
          description: |
            An absolute URI that identifies the specific occurrence of the
            problem. It may or may not yield further information if
            dereferenced.
