swagger: '2.0'
info:
  title: TMF908 - IoT Device Management
  description: |-
    ## MTN - TMF908 IoT Device Management

    ### Draft : 1.0 - September 2020

    This is the Swagger UI environment generated for MTNU - TMF908 IoT Device Management specification based on the standard TMF908 IoT Device Management v4.0

    ### Supported Operations
    - Retrieve Handset Details: This is used to know which handset a customer is using and all technical information about that handset
    - Send Internet Setting: This is used to push internet settings to a customer's handset.
    ### 2022-02-07
    - Moodified the /iotDevice post endpoint to handle samsung device uploaded
    ###  2023-05-04   Updated to conform to expected MADAPI Cloud implementation
  version: '1.0.3'
host: api.mtn.com
basePath: /v1/iotDeviceManagement
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  ApiKeyAuth:
    type: "apiKey"
    name: "X-API-Key"
    in: "header"
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.mtn.com/v1/oauth/access_token
security:
  - OAuth2: []
  - ApiKeyAuth: []    
parameters:
  apiKey:
    name: x-api-key
    description: API Key
    required: true
    in: header
    type: string
  transactionId:
    name: transactionId
    description: Client Transaction ID (optional if the targetSystem is DMC else required)
    required: false
    in: header
    type: string
tags:
  - name: Get Handset Details
  - name: Push Internet Settings
paths:
  /iotDeviceSpecification:
    get:
      operationId: listDeviceSpecs
      summary: List Device Specifications
      description: This operation lists a customer 's handset details
      tags:
        - Get Handset Details
      parameters:
        - $ref: '#/parameters/apiKey'
        - $ref: '#/parameters/transactionId'
        - name: relatedParty.id
          description: The customer's MSISDN for whom you want to know their handset information
          required: true
          in: query
          type: string
      responses:
        '200':
          description: OK
          headers:
            Transfer-Encoding:
              description: The Transfer-Encoding is chunked
              type: string
          schema:
            type: array
            items:
              $ref: '#/definitions/iotDeviceSpecification'
            example:
              - name: MSISDN
                description: '+256772122949'
              - name: handset.model
                description: 'GALAXY A51 (SM-A515F,DSN)'
              - name: handset.brandmodel
                description: 'SAMSUNG GALAXY A51 (SM-A515F,DSN)'
              - name: handset.os
                description: Google Android 9.0
              - name: dualsim.support
                description: 'Y'
              - name: screen.type
                description: TFT
              - name: touch.support
                description: 'N'
              - name: wap.push.si.support
                description: 'N'
              - name: wap.support
                description: 'Y'
              - name: oma.support
                description: ''
              - name: ota.support
                description: 'Y'
              - name: internet.support
                description: 'Y'
              - name: data.support
                description: 'Y'
              - name: handset.bearer
                description: GSM HSDPA UMTS GPRS
              - name: lte.support
                description: 'Y'
              - name: 4G.compatibility
                description: 'Y'
              - name: 3G.compatibility
                description: 'Y'
              - name: sub.imsi
                description: '641101910732323'
              - name: sub.imei
                description: '352351110599620'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /resourceSpecification:
    post:
      operationId: pushInternetSettings
      summary: Push internet settings to a customer's handset
      description: This operation pushes internet settings to a customer's handset
      tags:
        - Push Internet Settings
      parameters:
        - $ref: '#/parameters/apiKey'
        - $ref: '#/parameters/transactionId'
        - name: targetSystem
          description: Target system
          type: string
          in: header
          x-example: DAS

        - name: customer
          description: The Customer who will receive the internet settings
          required: true
          schema:
            $ref: '#/definitions/Customer'
          in: body
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/SuccessResponseBody'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  '/iotDevice':
    post:
      operationId: createIotDevice
      summary: Creates a IotDevice
      description: This operation creates a IotDevice entity.
      tags:
        - iotDevice
      parameters:
        - name: id
          description: MSDISDN of the user
          required: false
          type: string
          in: query
        - name: iotDevice
          description: The IotDevice to be created
          required: true
          schema:
            $ref: '#/definitions/IotDevice_Update'
          in: body
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              statusCode:
                type: string
                description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'"
              statusMessage:
                type: string
                description: "Status Message"
                example: "Success"
              transactionId:
                type: string
                description: "API generated Id to include for tracking requests"
              data:
                $ref: '#/definitions/IotDevice'
              _links:
                type: object
                properties:
                  self:
                    type: object
                    properties:
                      href:
                        type: string
                        example:  "https://api.mtn.com/tmf-api/iotDevice/v1/iotDevice"
        '201':
          description: Created
          schema:
            $ref: '#/definitions/IotDevice'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/Error'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Error'
        '403':
          description: Forbidden
          schema:
            $ref: '#/definitions/Error'
        '405':
          description: Method Not allowed
          schema:
            $ref: '#/definitions/Error'
        '409':
          description: Conflict
          schema:
            $ref: '#/definitions/Error'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
definitions:
  iotDeviceSpecification:
    type: object
    properties:
      name:
        type: string
        description: Device characteristic
        enum:
          - MSISDN
          - handset.model
          - handset.brandmodel
          - handset.os
          - dualsim.support
          - screen.type
          - touch.support
          - wap.push.si.support
          - wap.support
          - oma.support
          - ota.support
          - internet.support
          - data.support
          - handset.bearer
          - lte.support
          - 4G.compatibility
          - 3G.compatibility
          - sub.imsi
          - sub.imei
      description:
        type: string
        description: Value for the device characteristic
  Customer:
    type: object
    properties:
      name:
        type: string
        enum:
          - PUSH-SETTINGS
        description: Name of the operation being done
      description:
        type: string
        enum:
          - ALL
          - WAP
          - WEB
          - DATA
          - MMS
        description: Specify the internet settings to be pushed. Currently static to ALL. Defines the type of settings to be sent to the customer
      isBundle:
        type: boolean
        enum:
          - true
          - false
        description: set to true if sending ALL internet settings
      imei:
        type: string
        description: The device's IMEI
        example: 00000000000
      lang:
        type: string
        description: Language for the push settings to be sent in
        example: "ENG"
      relatedParty:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
              description: The customer's MSISDN
              example: '256789999781'
            name:
              type: string
              description: This key identifies that the id is the customer 's MSISDN. It' s value is static to SubscriberNumber
              enum:
                - SubscriberNumber

  SuccessResponseBody:
    type: object
    properties:
      statusCode:
        type: string
        description: "The status code of the response"
        example: '200'
      statusMessage:
        type: string
        description: "The status message of the response"
        example: "SUCCESS"
      id:
        type: string
        description: transactionId that was sent in the Request , can also be an actionId if targetSystem is DAS
        example: PaulMADAPiTest2020051112
      name:
        type: string
        enum:
          - PUSH-SETTINGS
        description: Name of the operation being done
      description:
        type: string
        enum:
          - ALL
        description: Specify the internet settings to be pushed. Currently static to ALL
      isBundle:
        type: boolean
        enum:
          - true
          - false
        description: set to true if sending ALL internet settings
      relatedParty:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
              description: The customer's MSISDN
              example: '256789999781'
            name:
              type: string
              description: This key identifies that the id is the customer 's MSISDN. It' s value is static to SubscriberNumber
              enum:
                - SubscriberNumber
  Error:
    description: 'Used when an API throws an Error,typically with a HTTP error response - code(3xx, 4xx, 5xx)'
    type: object
    required:
      - code
      - reason
    properties:
      code:
        type: string
        description: 'Application relevant detail, defined in the API or a common list.'
      reason:
        type: string
        description: Explanation of the reason for the error which can be shown to a client user.
      message:
        type: string
        description: More details and corrective actions related to the error which can be shown to a client user.
      status:
        type: string
        description: HTTP Error code extension
      referenceError:
        type: string
        format: uri
        description: URI of documentation describing the error.
      '@baseType':
        type: string
        description: 'When sub - classing, this defines the super - class.'
      '@schemaLocation':
        type: string
        format: uri
        description: A URI to a JSON - Schema file that defines additional attributes and relationships
      '@type':
        type: string
        description: 'When sub - classing, this defines the sub - class entity name.'
  IotDevice_Update:
    type: object
    description: Description of the device being modified
    properties:
      value:
        type: string
      serialNumber:
        type: string
      description:
        type: string
        description:  Message to be sent in the Samsung request
      deviceState:
        type: string
        description:  This is the action being taken on the device. It can be UPLOAD, LOCK, UNLOCK, ENROLL, COMPLETE and UNENROLL
        enum: [UPLOAD, LOCK, UNLOCK, ENROLL, UNENROLL, COMPLETE]
      provider:
        type: string
        description: Model of the device. This can be NOKIA or SAMSUNG
      id:
        type: string
        description: free-text description of the resource
      autoAccept:
        type: boolean
        description: This field is used to indicate whether the uploaded device(s) should be automatically added into the account or there is an approval required
      resourcerelationship:
        type: array
        items:
          type: object
          properties:
            resource:
              type: object
              properties:
                id:
                  type: string
                  description: ID of the device. This can be the device's IMEI
                value:
                  type: string
                  description: Additional information. For Samsung upload, this is the approver Id

  IotDevice:
    type: object
    description: 'Response from processing'
    required:
      - category
      - id
    properties:
      lifecycleState:
        type: string
        description: The life cycle state of the resource.
      value:
        type: string
      serialNumber:
        type: string
        description: NGSI Entity type
      createdOn:
        type: string
        format: date-time
      enrolledOn:
        type: string
        format: date-time
      updatedOn:
        type: string
        format: date-time
      model:
        type: string
        description: "Device model forexample Nokia"
      totalDeviceCount:
        type: string
        description: Total number of devices uploaded in the accoount
      validDeviceCount:
        type: string
        description: Total number of valid devices in the accoount
      invalidDeviceCount:
        type: string
        description: Total number of invalid devices uploaded in the accoount
      invalidReasons:
        type: array
        items:
          type: object
          properties:
            deviceUid:
              type: string
            reason:
              type: string