openapi: 3.1.0
info:
  title: ThingPark Notification Subscriber API
  version: '8.0'
  description: >
    REST interface for subscriber Notification.
servers:
  - url: 'https://community.thingpark.io/thingpark/notification/rest/1.0'
    description: Community
  - url: 'https://thingparkenterprise.eu.actility.com/thingpark/notification/rest/1.0'
    description: Europe
  - url: 'https://thingparkenterprise.us.actility.com/thingpark/notification/rest/1.0'
    description: United-States
  - url: 'https://thingparkenterprise.au.actility.com/thingpark/notification/rest/1.0'
    description: Australia
  - url: 'https://{hostname}/thingpark/notification/rest/1.0'
    description: Self-hosted TPE
    variables:
      hostname:
        default: enterprise.actility.local
        description: Hostname of the self-hosted TPE deployment
paths:
  /subscribers: {}
  '/subscribers/mine/notifications':
    get:
      tags:
        - notifications
      summary: Retrieve Notifications
      description: |
        Retrieve a list of Notifications associated with the Subscriber.

        ### Access rights:
        - `<Subscriber>/x`
        - If the authenticated user has domain restrictions, only notifications
          matching the domain restrictions can be retrieved.
      parameters:
        - name: applicationType
          in: query
          description: Application type filtering (exact match)
          schema:
            type: string
            enum:
              - DEVICE_MANAGER
        - name: state
          in: query
          description: Notification state (exact match)
          schema:
            type: string
            enum:
              - PENDING
              - IN_PROGRESS
              - COMPLETED
        - name: result
          in: query
          description: Task result (exact match)
          schema:
            type: string
            enum:
              - PENDING
              - SUCCESS
              - ERROR
        - name: taskType
          in: query
          description: Task type filtering (exact match)
          schema:
            type: string
            enum:
              - DEVICE_CREATE
              - DEVICE_DELETE
              - DEVICE_MASS_OPERATION
              - MG_CREATE
              - MG_DELETE
        - name: userID
          in: query
          description: User ID filtering (exact match)
          schema:
            type: string
          example: tpk-100072853
        - name: from
          in: query
          description: |
            Only returns notifications created on or after this timestamp.
            Syntax: ISO 8601 timestamp with time zone designator.
          schema:
            type: string
            format: date-time
          example: "2018-08-24T09:27:59.512Z"
        - name: to
          in: query
          description: |
            Only returns notifications created on or before this timestamp.
            Syntax: ISO 8601 timestamp with time zone designator.
          schema:
            type: string
            format: date-time
          example: "2018-08-24T09:27:59.512Z"
        - name: size
          in: query
          description: Maximum number of notifications to return. When this query
            parameter is not specified in the request, all elements are returned
            (no pagination).
          schema:
            type: integer
          example: 100
      responses:
        '200':
          $ref: '#/components/responses/Notifications'
        default:
          $ref: '#/components/responses/Error'
    parameters: []
  '/subscribers/mine/notifications/{notificationID}':
    get:
      tags:
        - notifications
      summary: Retrieve a Notification
      description: |
        Retrieve a Notification associated with the Subscriber.

        ### Access rights:
        - `<Subscriber>/x`
        - If the authenticated user has domain restrictions, the notification
          must match the domain restrictions.
      responses:
        '200':
          $ref: '#/components/responses/Notification'
        default:
          $ref: '#/components/responses/Error'
    parameters:
      - $ref: '#/components/parameters/Notification'
components:
  schemas:
    Notifications:
      type: object
      readOnly: true
      properties:
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
          example:
            - taskResult:
                taskID: 5731998ee4b07e88a83b23b1
                applicationType: DEVICE_MANAGER
                state: COMPLETED
                creationTimestamp: "2018-04-06T12:16:26.267Z"
                updateTimestamp: "2018-04-09T14:35:01.830Z"
                ownerID: "199906993"
                resourceID: F03D291E001001C9
                userID: tpk-100072853
                userName: John Doe
                subTasks:
                  total: 1
                  success: 1
                  error: 0
                  abort: 0
                action:
                  taskType: DEVICE_CREATE
                  result: SUCCESS
                  href: /thingpark/wireless/rest/subscriptions/33/devices/2056
                domains:
                  - name: France/Paris
                    group:
                      name: Site
                  - name: Location
                    group:
                      name: Vertical
            - taskResult:
                taskID: 5731998ee4b07e88a83b23b1
                applicationType: DEVICE_MANAGER
                state: IN_PROGRESS
                creationTimestamp: "2018-04-06T12:16:26.267Z"
                updateTimestamp: "2018-04-09T14:35:01.830Z"
                ownerID: "199906993"
                userID: tpk-100072853
                userName: John Doe
                subTasks:
                  total: 184
                  success: 52
                  error: 2
                  abort: 0
                action:
                  taskType: DEVICE_MASS_OPERATION
                  result: ERROR
                  code: 270
                  csv:
                    - "999900FFFF002993,line 6,[111] A Device report already
                      exists for the given EUI"
                    - "999900FFFF002993,line 7,[111] A Device report already
                      exists for the given EUI,[222] No device profile for the
                      given ID : SMTC/LoRaMote.1"
                domains:
                  - name: France/Paris
                    group:
                      name: Site
                  - name: Location
                    group:
                      name: Vertical
    Notification:
      type: object
      readOnly: true
      properties:
        taskResult:
          type: object
          properties:
            taskID:
              type: string
              description: Task ID
            applicationType:
              type: string
              enum:
                - DEVICE_MANAGER
              description: |
                Type of the application associated with the Task:
                - DEVICE_MANAGER: Device Manager application
            state:
              type: string
              enum:
                - PENDING
                - IN_PROGRESS
                - COMPLETED
              description: |
                State of the Task:
                - PENDING: the Task is not yet started
                - IN_PROGRESS: the Task execution is in progress
                - COMPLETED: the Task execution is completed
            creationTimestamp:
              type: string
              format: date-time
              description: Creation timestamp of the Task
            updateTimestamp:
              type: string
              format: date-time
              description: Last update timestamp of the Task
            ownerID:
              type: string
              description: Owner ID of the Task (Subscriber ID)
            resourceID:
              type:
                - string
                - "null"
              description: ID of the resource associated with the Task
            userID:
              type: string
              description: ID of user who executed the Task
            userName:
              type: string
              description: Name of user who executed the Task
            subTasks:
              type: object
              properties:
                total:
                  type: integer
                  description: Total number of Sub-Tasks
                success:
                  type: integer
                  description: Number of completed Sub-Tasks in success
                error:
                  type: integer
                  description: Number of completed Sub-Tasks in error
                abort:
                  type: integer
                  description: Number of aborted Sub-Tasks
              required:
                - total
                - success
                - error
                - abort
            action:
              type: object
              oneOf:
                - $ref: '#/components/schemas/DeviceCreate'
                - $ref: '#/components/schemas/DeviceDelete'
                - $ref: '#/components/schemas/DeviceMassOperation'
                - $ref: '#/components/schemas/MulticastGroupCreate'
                - $ref: '#/components/schemas/MulticastGroupDelete'
              discriminator:
                propertyName: taskType
                mapping:
                  DEVICE_CREATE: '#/components/schemas/DeviceCreate'
                  DEVICE_DELETE: '#/components/schemas/DeviceDelete'
                  DEVICE_MASS_OPERATION: '#/components/schemas/DeviceMassOperation'
                  MG_CREATE: '#/components/schemas/MulticastGroupCreate'
                  MG_DELETE: '#/components/schemas/MulticastGroupDelete'
            domains:
              type: array
              description: |
                List of domains associated with the Device. The list cannot
                contain more than one domain for a given group.
              items:
                type: object
                description: |
                  The domain must exist in the subscriber account and must be in `ACTIVE`
                  state to be used.
                required:
                  - name
                  - group
                properties:
                  name:
                    type: string
                    description: Domain name
                    example: France/Paris
                  group:
                    type: object
                    required:
                      - name
                    properties:
                      name:
                        type: string
                        description: Domain group name
                        example: Site
              example:
                - name: France/Paris
                  group:
                    name: Site
                - name: Location
                  group:
                    name: Vertical
          required:
            - taskID
            - applicationType
            - state
            - creationTimestamp
            - ownerID
            - userID
            - userName
            - subTasks
            - action
      required:
        - taskResult
      example:
        taskResult:
          taskID: 5731998ee4b07e88a83b23b1
          applicationType: DEVICE_MANAGER
          state: COMPLETED
          creationTimestamp: "2018-04-06T12:16:26.267Z"
          updateTimestamp: "2018-04-09T14:35:01.830Z"
          ownerID: "199906993"
          resourceID: F03D291E001001C9
          userID: tpk-100072853
          userName: John Doe
          subTasks:
            total: 1
            success: 1
            error: 0
            abort: 0
          action:
            taskType: DEVICE_CREATE
            result: SUCCESS
            href: /thingpark/wireless/rest/subscriptions/33/devices/2056
          domains:
            - name: France/Paris
              group:
                name: Site
            - name: Location
              group:
                name: Vertical
    DeviceCreate:
      title: DEVICE_CREATE
      type: object
      oneOf:
        - $ref: '#/components/schemas/TaskPending'
        - $ref: '#/components/schemas/TaskCreateSuccess'
        - $ref: '#/components/schemas/TaskError'
      properties:
        taskType:
          type: string
          enum:
            - DEVICE_CREATE
          description: |
            Type of Task:
            - DEVICE_CREATE: Create a Device
            - DEVICE_DELETE: Delete a Device
            - DEVICE_MASS_OPERATION: Create and/or Delete Devices in mass
            - MG_CREATE: Create a Multicast Group
            - MG_DELETE: Delete a Multicast Group
      required:
        - taskType
      discriminator:
        propertyName: result
        mapping:
          PENDING: '#/components/schemas/TaskPending'
          SUCCESS: '#/components/schemas/TaskCreateSuccess'
          ERROR: '#/components/schemas/TaskError'
    DeviceDelete:
      title: DEVICE_DELETE
      type: object
      oneOf:
        - $ref: '#/components/schemas/TaskPending'
        - $ref: '#/components/schemas/TaskDeleteSuccess'
        - $ref: '#/components/schemas/TaskError'
      properties:
        taskType:
          type: string
          enum:
            - DEVICE_DELETE
          description: |
            Type of Task:
            - DEVICE_CREATE: Create a Device
            - DEVICE_DELETE: Delete a Device
            - DEVICE_MASS_OPERATION: Create and/or Delete Devices in mass
            - MG_CREATE: Create a Multicast Group
            - MG_DELETE: Delete a Multicast Group
      required:
        - taskType
      discriminator:
        propertyName: result
        mapping:
          PENDING: '#/components/schemas/TaskPending'
          SUCCESS: '#/components/schemas/TaskDeleteSuccess'
          ERROR: '#/components/schemas/TaskError'
    DeviceMassOperation:
      title: DEVICE_MASS_OPERATION
      type: object
      oneOf:
        - $ref: '#/components/schemas/TaskPending'
        - $ref: '#/components/schemas/DeviceMassOperationSuccess'
        - $ref: '#/components/schemas/DeviceMassOperationError'
      properties:
        taskType:
          type: string
          enum:
            - DEVICE_MASS_OPERATION
          description: |
            Type of Task:
            - DEVICE_CREATE: Create a Device
            - DEVICE_DELETE: Delete a Device
            - DEVICE_MASS_OPERATION: Create and/or Delete Devices in mass
            - MG_CREATE: Create a Multicast Group
            - MG_DELETE: Delete a Multicast Group
      required:
        - taskType
      discriminator:
        propertyName: result
        mapping:
          PENDING: '#/components/schemas/TaskPending'
          SUCCESS: '#/components/schemas/DeviceMassOperationSuccess'
          ERROR: '#/components/schemas/DeviceMassOperationError'
    DeviceMassOperationSuccess:
      title: SUCCESS
      type: object
      properties:
        result:
          type: string
          enum:
            - SUCCESS
          description: |
            Result of Device mass operation:
            - PENDING: the Device mass operation is not yet processed
            - SUCCESS: the Device mass operation fully succeeded
            - ERROR: the Device mass operation failed
      required:
        - result
    DeviceMassOperationError:
      title: ERROR
      type: object
      properties:
        result:
          type: string
          enum:
            - ERROR
          description: |
            Result of Device mass operation:
            - PENDING: the Device mass operation is not yet processed
            - SUCCESS: the Device mass operation fully succeeded
            - ERROR: the Device mass operation failed
        code:
          type: integer
          description: Error code
        csv:
          type: array
          items:
            type: string
          description: CSV error lines
      required:
        - result
        - code
        - csv
    MulticastGroupCreate:
      title: MG_CREATE
      type: object
      oneOf:
        - $ref: '#/components/schemas/TaskPending'
        - $ref: '#/components/schemas/TaskCreateSuccess'
        - $ref: '#/components/schemas/TaskError'
      properties:
        taskType:
          type: string
          enum:
            - MG_CREATE
          description: |
            Type of Task:
            - DEVICE_CREATE: Create a Device
            - DEVICE_DELETE: Delete a Device
            - DEVICE_MASS_OPERATION: Create and/or Delete Devices in mass
            - MG_CREATE: Create a Multicast Group
            - MG_DELETE: Delete a Multicast Group
      required:
        - taskType
      discriminator:
        propertyName: result
        mapping:
          PENDING: '#/components/schemas/TaskPending'
          SUCCESS: '#/components/schemas/TaskCreateSuccess'
          ERROR: '#/components/schemas/TaskError'
    MulticastGroupDelete:
      title: MG_DELETE
      type: object
      oneOf:
        - $ref: '#/components/schemas/TaskPending'
        - $ref: '#/components/schemas/TaskDeleteSuccess'
        - $ref: '#/components/schemas/TaskError'
      properties:
        taskType:
          type: string
          enum:
            - MG_DELETE
          description: |
            Type of Task:
            - DEVICE_CREATE: Create a Device
            - DEVICE_DELETE: Delete a Device
            - DEVICE_MASS_OPERATION: Create and/or Delete Devices in mass
            - MG_CREATE: Create a Multicast Group
            - MG_DELETE: Delete a Multicast Group
      required:
        - taskType
      discriminator:
        propertyName: result
        mapping:
          PENDING: '#/components/schemas/TaskPending'
          SUCCESS: '#/components/schemas/TaskDeleteSuccess'
          ERROR: '#/components/schemas/TaskError'
    TaskCreateSuccess:
      title: SUCCESS
      type: object
      properties:
        result:
          type: string
          enum:
            - SUCCESS
          description: |
            Result of Device creation:
            - PENDING: the Device creation is not yet processed
            - SUCCESS: the Device creation succeeded
            - ERROR: the Device creation failed
        href:
          type: string
          description: HREF of the created resource
      required:
        - result
        - href
    TaskDeleteSuccess:
      title: SUCCESS
      type: object
      properties:
        result:
          type: string
          enum:
            - SUCCESS
          description: |
            Result of Device deletion:
            - PENDING: the Device deletion is not yet processed
            - SUCCESS: the Device deletion succeeded
            - ERROR: the Device deletion failed
      required:
        - result
    TaskError:
      title: ERROR
      type: object
      properties:
        result:
          type: string
          enum:
            - ERROR
          description: |
            Result of Device creation:
            - PENDING: the Device creation is not yet processed
            - SUCCESS: the Device creation succeeded
            - ERROR: the Device creation failed
        code:
          type: integer
          description: Error code
        message:
          type: string
          description: Error technical message
        info1:
          type: string
          description: Error information 1
        info2:
          type: string
          description: Error information 2
        info3:
          type: string
          description: Error information 3
      required:
        - result
        - code
        - message
    TaskPending:
      title: PENDING
      type: object
      properties:
        result:
          type: string
          enum:
            - PENDING
          description: |
            Result of Device creation:
            - PENDING: the Device creation is not yet processed
            - SUCCESS: the Device creation succeeded
            - ERROR: the Device creation failed
      required:
        - result
    Error:
      type: object
      required:
        - code
        - message
      readOnly: true
      properties:
        code:
          type: integer
          format: int32
          description: Error code
          example: 25
        message:
          type: string
          description: Error message
          example: unknown error
  responses:
    Notifications:
      description: Successful RETRIEVE
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Notifications'
    Notification:
      description: Successful RETRIEVE
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Notification'
    Error:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    Notification:
      name: notificationID
      in: path
      description: Notification ID
      required: true
      schema:
        type: string
        example: 5a532e0b885ff2205364f897
  requestBodies: {}
  headers: {}
  securitySchemes:
    "Subscriber_service_account":
      type: oauth2
      description: Authenticate using subscriber service account credentials
      flows:
        clientCredentials:
          tokenUrl: "/users-auth/protocol/openid-connect/token"
          scopes: {}
  links: {}
  callbacks: {}
security:
  - "Subscriber_service_account": []
tags:
  - name: notifications
    description: Notifications
