3GPP NIDD configurations API

openapi: 3.2.0
info:
  title: 3gpp-nidd NIDD configurations API
  version: 1.3.0
  description: "API for non IP data delivery.  \n© 2024, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  \nAll rights reserved.\n"
servers:
- url: '{apiRoot}/3gpp-nidd/v1'
  variables:
    apiRoot:
      default: https://example.com
      description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.
security:
- {}
- oAuth2ClientCredentials: []
tags:
- name: NIDD configurations
paths:
  /{scsAsId}/configurations:
    parameters:
    - name: scsAsId
      description: String identifying the SCS/AS.
      in: path
      required: true
      schema:
        type: string
    get:
      summary: Read all NIDD configuration resources for a given SCS/AS.
      operationId: FetchAllNIDDConfigurations
      tags:
      - NIDD configurations
      responses:
        '200':
          description: all NIDD configurations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NiddConfiguration'
                minItems: 0
                description: individual NIDD configuration.
        '307':
          $ref: TS29122_CommonData.yaml#/components/responses/307
        '308':
          $ref: TS29122_CommonData.yaml#/components/responses/308
        '400':
          $ref: TS29122_CommonData.yaml#/components/responses/400
        '401':
          $ref: TS29122_CommonData.yaml#/components/responses/401
        '403':
          $ref: TS29122_CommonData.yaml#/components/responses/403
        '404':
          $ref: TS29122_CommonData.yaml#/components/responses/404
        '406':
          $ref: TS29122_CommonData.yaml#/components/responses/406
        '429':
          $ref: TS29122_CommonData.yaml#/components/responses/429
        '500':
          $ref: TS29122_CommonData.yaml#/components/responses/500
        '503':
          $ref: TS29122_CommonData.yaml#/components/responses/503
        default:
          $ref: TS29122_CommonData.yaml#/components/responses/default
    post:
      summary: Create a new NIDD configuration resource.
      operationId: CreateNIDDConfiguration
      tags:
      - NIDD configurations
      requestBody:
        description: Contains the data to create a NIDD configuration.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NiddConfiguration'
      responses:
        '201':
          description: NIDD configuration is successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NiddConfiguration'
          headers:
            Location:
              description: Contains the URI of the newly created resource
              required: true
              schema:
                type: string
        '400':
          $ref: TS29122_CommonData.yaml#/components/responses/400
        '401':
          $ref: TS29122_CommonData.yaml#/components/responses/401
        '403':
          $ref: TS29122_CommonData.yaml#/components/responses/403
        '404':
          $ref: TS29122_CommonData.yaml#/components/responses/404
        '411':
          $ref: TS29122_CommonData.yaml#/components/responses/411
        '413':
          $ref: TS29122_CommonData.yaml#/components/responses/413
        '415':
          $ref: TS29122_CommonData.yaml#/components/responses/415
        '429':
          $ref: TS29122_CommonData.yaml#/components/responses/429
        '500':
          $ref: TS29122_CommonData.yaml#/components/responses/500
        '503':
          $ref: TS29122_CommonData.yaml#/components/responses/503
        default:
          $ref: TS29122_CommonData.yaml#/components/responses/default
      callbacks:
        niddNotifications:
          '{$request.body#/notificationDestination}':
            post:
              requestBody:
                description: "Notification for NIDD configuration status, MO NIDD, MT NIDD delivery report. \n"
                required: true
                content:
                  application/json:
                    schema:
                      oneOf:
                      - $ref: '#/components/schemas/NiddConfigurationStatusNotification'
                      - $ref: '#/components/schemas/NiddUplinkDataNotification'
                      - $ref: '#/components/schemas/NiddDownlinkDataDeliveryStatusNotification'
                      - $ref: '#/components/schemas/GmdNiddDownlinkDataDeliveryNotification'
                      - $ref: '#/components/schemas/ManagePortNotification'
              responses:
                '204':
                  description: Expected response to a successful callback processing without a body
                '200':
                  description: Expected response to a successful callback processing with a body
                  content:
                    application/json:
                      schema:
                        $ref: TS29122_CommonData.yaml#/components/schemas/Acknowledgement
                '307':
                  $ref: TS29122_CommonData.yaml#/components/responses/307
                '308':
                  $ref: TS29122_CommonData.yaml#/components/responses/308
                '400':
                  $ref: TS29122_CommonData.yaml#/components/responses/400
                '401':
                  $ref: TS29122_CommonData.yaml#/components/responses/401
                '403':
                  $ref: TS29122_CommonData.yaml#/components/responses/403
                '404':
                  $ref: TS29122_CommonData.yaml#/components/responses/404
                '411':
                  $ref: TS29122_CommonData.yaml#/components/responses/411
                '413':
                  $ref: TS29122_CommonData.yaml#/components/responses/413
                '415':
                  $ref: TS29122_CommonData.yaml#/components/responses/415
                '429':
                  $ref: TS29122_CommonData.yaml#/components/responses/429
                '500':
                  $ref: TS29122_CommonData.yaml#/components/responses/500
                '503':
                  $ref: TS29122_CommonData.yaml#/components/responses/503
                default:
                  $ref: TS29122_CommonData.yaml#/components/responses/default
components:
  schemas:
    NiddConfigurationStatusNotification:
      description: Represents an NIDD configuration status notification.
      type: object
      properties:
        niddConfiguration:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        status:
          $ref: '#/components/schemas/NiddStatus'
        rdsCapIndication:
          type: boolean
          description: 'It indicates whether the network capability for the reliable data service is enabled or not.

            '
        rdsPort:
          $ref: '#/components/schemas/RdsPort'
      required:
      - niddConfiguration
      - status
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
    NiddDownlinkDataTransfer:
      description: Represents the received NIDD downlink data from the SCS/AS.
      type: object
      properties:
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        externalGroupId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalGroupId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        self:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        data:
          $ref: TS29122_CommonData.yaml#/components/schemas/Bytes
        reliableDataService:
          type: boolean
          description: 'Indicates whether the reliable data service (as defined in clause 4.5.14.3 of 3GPP TS 23.682) acknowledgement is requested (true) or not (false). Default value is false.

            '
        rdsPort:
          $ref: '#/components/schemas/RdsPort'
        maximumLatency:
          $ref: TS29122_CommonData.yaml#/components/schemas/DurationSec
        priority:
          type: integer
          description: 'It is used to indicate the priority of the non-IP data packet relative to other non-IP data packets.

            '
        pdnEstablishmentOption:
          $ref: '#/components/schemas/PdnEstablishmentOptions'
        deliveryStatus:
          $ref: '#/components/schemas/DeliveryStatus'
        requestedRetransmissionTime:
          $ref: TS29122_CommonData.yaml#/components/schemas/DateTime
      required:
      - data
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
      - required:
        - externalGroupId
    NiddConfiguration:
      description: Represents the configuration for NIDD.
      type: object
      properties:
        self:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        supportedFeatures:
          $ref: TS29571_CommonData.yaml#/components/schemas/SupportedFeatures
        mtcProviderId:
          type: string
          description: Identifies the MTC Service Provider and/or MTC Application.
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        externalGroupId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalGroupId
        duration:
          $ref: TS29122_CommonData.yaml#/components/schemas/DateTime
        reliableDataService:
          type: boolean
          description: 'Indicates whether the reliable data service (as defined in clause 4.5.14.3 of 3GPP TS  23.682) acknowledgement is requested (true) or not (false). Default value is false.

            '
        rdsPorts:
          type: array
          items:
            $ref: '#/components/schemas/RdsPort'
          minItems: 1
          description: 'Indicates the static port configuration that is used for reliable data transfer between specific applications using RDS (as defined in clause 5.2.4 and 5.2.5 of 3GPP TS 24.250).

            '
        pdnEstablishmentOption:
          $ref: '#/components/schemas/PdnEstablishmentOptions'
        notificationDestination:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        requestTestNotification:
          type: boolean
          description: 'Set to true by the SCS/AS to request the SCEF to send a test notification as defined in clause 5.2.5.3. Set to false or omitted otherwise.

            '
        websockNotifConfig:
          $ref: TS29122_CommonData.yaml#/components/schemas/WebsockNotifConfig
        maximumPacketSize:
          type: integer
          minimum: 1
          description: 'The Maximum Packet Size is the maximum NIDD packet size that was transferred to the UE by the SCEF in the PCO, see clause 4.5.14.1 of 3GPP TS 23.682. If no maximum packet size was provided to the UE by the SCEF, the SCEF sends a default configured max packet size to SCS/AS. Unit  bit.

            '
          readOnly: true
        niddDownlinkDataTransfers:
          type: array
          items:
            $ref: '#/components/schemas/NiddDownlinkDataTransfer'
          minItems: 1
          description: "The downlink data deliveries that needed to be executed by the SCEF. The cardinality of the property shall be 0..1 in the request and 0..N in the response (i.e. response may\n contain multiple buffered MT NIDD).\n"
        status:
          $ref: '#/components/schemas/NiddStatus'
      required:
      - notificationDestination
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
      - required:
        - externalGroupId
    DeliveryStatus:
      anyOf:
      - type: string
        enum:
        - SUCCESS
        - SUCCESS_NEXT_HOP_ACKNOWLEDGED
        - SUCCESS_NEXT_HOP_UNACKNOWLEDGED
        - SUCCESS_ACKNOWLEDGED
        - SUCCESS_UNACKNOWLEDGED
        - TRIGGERED
        - BUFFERING
        - BUFFERING_TEMPORARILY_NOT_REACHABLE
        - SENDING
        - FAILURE
        - FAILURE_RDS_DISABLED
        - FAILURE_NEXT_HOP
        - FAILURE_TIMEOUT
        - FAILURE_TEMPORARILY_NOT_REACHABLE
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents the status of a downlink NIDD data delivery resource.  \nPossible values are:\n- SUCCESS: Success but details not provided\n- SUCCESS_NEXT_HOP_ACKNOWLEDGED: Successful delivery to the next hop with acknowledgment.\n- SUCCESS_NEXT_HOP_UNACKNOWLEDGED: Successful delivery to the next hop without\n  acknowledgment\n- SUCCESS_ACKNOWLEDGED: Reliable delivery was acknowledged by the UE\n- SUCCESS_UNACKNOWLEDGED: Reliable delivery was not acknowledged by the UE\n- TRIGGERED: The SCEF triggered the device and is buffering the data.\n- BUFFERING: The SCEF is buffering the data due to no PDN connection established.\n- BUFFERING_TEMPORARILY_NOT_REACHABLE: The SCEF has been informed that the UE is temporarily\n  not reachable but is buffering the data\n- SENDING: The SCEF has forwarded the data, but they may be stored elsewhere\n- FAILURE: Delivery failure but details not provided\n- FAILURE_RDS_DISABLED: RDS was disabled\n- FAILURE_NEXT_HOP: Unsuccessful delivery to the next hop.\n- FAILURE_TIMEOUT: Unsuccessful delivery due to timeout. \n- FAILURE_TEMPORARILY_NOT_REACHABLE: The SCEF has been informed that the UE is temporarily\n  not reachable without buffering the data.\n"
      readOnly: true
    NiddStatus:
      anyOf:
      - type: string
        enum:
        - ACTIVE
        - TERMINATED_UE_NOT_AUTHORIZED
        - TERMINATED
        - RDS_PORT_UNKNOWN
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents the status of a NIDD configuration.  \nPossible values are:\n- ACTIVE: The NIDD configuration is active.\n- TERMINATED_UE_NOT_AUTHORIZED: The NIDD configuration was terminated because the UE´s\n  authorisation was revoked.\n- TERMINATED: The NIDD configuration was terminated.\n- RDS_PORT_UNKNOWN: The RDS port is unknown.\n"
      readOnly: true
    ManageEntity:
      anyOf:
      - type: string
        enum:
        - UE
        - AS
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents the origin that manages the RDS port.  \nPossible values are:\n- UE: Representing the UE.\n- AS: Representing the Application Server.\n"
      readOnly: true
    NiddDownlinkDataDeliveryStatusNotification:
      description: Represents the delivery status of a specific NIDD downlink data delivery.
      type: object
      properties:
        niddDownlinkDataTransfer:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        deliveryStatus:
          $ref: '#/components/schemas/DeliveryStatus'
        requestedRetransmissionTime:
          $ref: TS29122_CommonData.yaml#/components/schemas/DateTime
      required:
      - niddDownlinkDataTransfer
      - deliveryStatus
    PdnEstablishmentOptions:
      anyOf:
      - type: string
        enum:
        - WAIT_FOR_UE
        - INDICATE_ERROR
        - SEND_TRIGGER
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents PDN establishment options that describe the network behaviour when\nthere is no PDN connection towards the addressed UE.  \nPossible values are:\n- WAIT_FOR_UE: wait for the UE to establish the PDN connection \n- INDICATE_ERROR: respond with an error cause\n- SEND_TRIGGER: send a device trigger\n"
    GmdNiddDownlinkDataDeliveryNotification:
      description: Represents the delivery status of a specific group NIDD downlink data delivery.
      type: object
      properties:
        niddDownlinkDataTransfer:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        gmdResults:
          type: array
          items:
            $ref: '#/components/schemas/GmdResult'
          minItems: 1
          description: Indicates the group message delivery result.
      required:
      - niddDownlinkDataTransfer
      - gmdResults
    ManagePort:
      description: Represents the configuration of a RDS dynamic port management.
      type: object
      properties:
        self:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        appId:
          type: string
          description: Identifies the application.
        manageEntity:
          $ref: '#/components/schemas/ManageEntity'
        skipUeInquiry:
          type: boolean
          description: Indicate whether to skip UE inquiry.
        supportedFormats:
          type: array
          items:
            $ref: '#/components/schemas/SerializationFormat'
          minItems: 1
          description: 'Indicates the serialization format(s) that are supported by the SCS/AS on the associated RDS port.

            '
        configuredFormat:
          $ref: '#/components/schemas/SerializationFormat'
      required:
      - appId
    NiddUplinkDataNotification:
      description: Represents NIDD uplink data to be notified to the SCS/AS.
      type: object
      properties:
        niddConfiguration:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        data:
          $ref: TS29122_CommonData.yaml#/components/schemas/Bytes
        reliableDataService:
          type: boolean
          description: 'Indicates whether the reliable data service acknowledgement is requested (true) or not (false).

            '
        rdsPort:
          $ref: '#/components/schemas/RdsPort'
      required:
      - niddConfiguration
      - data
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
    SerializationFormat:
      anyOf:
      - type: string
        enum:
        - CBOR
        - JSON
        - XML
      - type: string
        description: 'This string provides forward-compatibility with future extensions to the enumeration but is not used to encode content defined in the present version of this API.

          '
      description: "Represents a serialization format associated with an RDS port which is applicable\nfor the Rds_serialization_format feature.\nPossible values are\n- CBOR: The CBOR Serialzition format \n- JSON: The JSON Serialzition format\n- XML: The XML Serialzition format\n"
    RdsPort:
      description: Represents the port configuration for Reliable Data Transfer.
      type: object
      properties:
        portUE:
          $ref: TS29122_CommonData.yaml#/components/schemas/Port
        portSCEF:
          $ref: TS29122_CommonData.yaml#/components/schemas/Port
      required:
      - portUE
      - portSCEF
    GmdResult:
      description: Represents the group message delivery result.
      type: object
      properties:
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        deliveryStatus:
          $ref: '#/components/schemas/DeliveryStatus'
        requestedRetransmissionTime:
          $ref: TS29122_CommonData.yaml#/components/schemas/DateTime
      required:
      - deliveryStatus
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
    ManagePortNotification:
      description: Represents a ManagePort notification of port numbers that are reserved.
      type: object
      properties:
        niddConfiguration:
          $ref: TS29122_CommonData.yaml#/components/schemas/Link
        externalId:
          $ref: TS29122_CommonData.yaml#/components/schemas/ExternalId
        msisdn:
          $ref: TS29122_CommonData.yaml#/components/schemas/Msisdn
        managedPorts:
          type: array
          items:
            $ref: '#/components/schemas/ManagePort'
          minItems: 1
          description: Indicates the reserved RDS port configuration information.
      required:
      - niddConfiguration
      oneOf:
      - required:
        - externalId
      - required:
        - msisdn
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}
externalDocs:
  description: 3GPP TS 29.122 V18.6.0 T8 reference point for Northbound APIs
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.122/