A.7 DeviceTriggering API

29.1223GPPRelease 18T8 reference point for Northbound APIsTS

openapi: 3.0.0

info:

title: 3gpp-device-triggering

version: 1.2.0

description: |

API for device trigger.

© 2022, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).

All rights reserved.

externalDocs:

description: 3GPP TS 29.122 V17.6.0 T8 reference point for Northbound APIs

url: ‘https://www.3gpp.org/ftp/Specs/archive/29_series/29.122/’

security:

– {}

– oAuth2ClientCredentials: []

servers:

– url: ‘{apiRoot}/3gpp-device-triggering/v1’

variables:

apiRoot:

default: https://example.com

description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.

paths:

/{scsAsId}/transactions:

get:

summary: read all active device triggering transactions for a given SCS/AS.

operationId: FetchAllDeviceTriggeringTransactions

tags:

– Device Triggering Transactions

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

responses:

‘200’:

description: OK (Successful get all of the active device triggering transactions for the SCS/AS)

content:

application/json:

schema:

type: array

items:

$ref: ‘#/components/schemas/DeviceTriggering’

‘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 long-term transaction for a device triggering.

operationId: CreateDeviceTriggeringTransaction

tags:

– Device Triggering API Transactions

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

requestBody:

description: Parameters to request a device triggering delivery.

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

callbacks:

notificationDestination:

‘{request.body#/notificationDestination}’:

post:

requestBody: # contents of the callback message

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggeringDeliveryReportNotification’

responses:

‘200’:

description: OK (successful notification)

content:

application/json:

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Acknowledgement’

‘204’:

description: No Content (successful notification)

‘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’

responses:

‘201’:

description: Created (Successful creation of subscription)

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

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’

/{scsAsId}/transactions/{transactionId}:

get:

summary: Read a device triggering transaction resource.

operationId: FetchIndDeviceTriggeringTransaction

tags:

– Individual Device Triggering Transaction

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

– name: transactionId

in: path

description: Identifier of the transaction resource

required: true

schema:

type: string

responses:

‘200’:

description: OK (Successful get the active subscription)

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

‘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’

put:

summary: Replace an existing device triggering transaction resource and the corresponding device trigger request.

operationId: UpdateIndDeviceTriggeringTransaction

tags:

– Individual Device Triggering Transaction

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

– name: transactionId

in: path

description: Identifier of the transaction resource

required: true

schema:

type: string

requestBody:

description: Parameters to update/replace the existing device triggering

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

responses:

‘200’:

description: OK (Successful update of the device triggering)

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

‘204’:

description: No Content (Successful update of the device triggering)

‘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’

patch:

summary: Modify an existing Individual Device Triggering Transaction resource and the corresponding device triggering request.

operationId: ModifyIndDeviceTriggeringTransaction

tags:

– Individual Device Triggering Transaction

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

– name: transactionId

in: path

description: Identifier of the transaction resource

required: true

schema:

type: string

requestBody:

description: Parameters to request the modification of the existing Individual Device Triggering Transaction resource.

required: true

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggeringPatch’

responses:

‘200’:

description: OK. The Individual Device Triggering Transaction resource was successfully modified and a representation of the modified Individual Device Triggering Transaction resource within the DeviceTriggering data structure including the "deliveryResult" attribute is returned by the SCEF.

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

‘204’:

description: No Content. The Individual Device Triggering Transaction resource was successfully modified no content is returned in the response message body.

‘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’

delete:

summary: Deletes an already existing device triggering transaction.

operationId: DeleteIndDeviceTriggeringTransaction

tags:

– Individual Device Triggering Transaction

parameters:

– name: scsAsId

in: path

description: Identifier of the SCS/AS

required: true

schema:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ScsAsId’

– name: transactionId

in: path

description: Identifier of the transaction resource

required: true

schema:

type: string

responses:

‘204’:

description: No Content (Successful deletion of the existing subscription)

‘200’:

description: OK (Successful deletion of the existing subscription)

content:

application/json:

schema:

$ref: ‘#/components/schemas/DeviceTriggering’

‘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’

‘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:

securitySchemes:

oAuth2ClientCredentials:

type: oauth2

flows:

clientCredentials:

tokenUrl: ‘{tokenUrl}’

scopes: {}

schemas:

DeviceTriggering:

description: Represents device triggering related information.

type: object

properties:

self:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Link’

externalId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/ExternalId’

msisdn:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Msisdn’

supportedFeatures:

$ref: ‘TS29571_CommonData.yaml#/components/schemas/SupportedFeatures’

validityPeriod:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/DurationSec’

priority:

$ref: ‘#/components/schemas/Priority’

applicationPortId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Port’

appSrcPortId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Port’

triggerPayload:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Bytes’

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’

deliveryResult:

$ref: ‘#/components/schemas/DeliveryResult’

required:

– validityPeriod

– priority

– applicationPortId

– triggerPayload

– notificationDestination

oneOf:

– required: [externalId]

– required: [msisdn]

DeviceTriggeringDeliveryReportNotification:

description: Represents a device triggering delivery report notification.

type: object

properties:

transaction:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Link’

result:

$ref: ‘#/components/schemas/DeliveryResult’

required:

– transaction

– result

DeviceTriggeringPatch:

description: Represents device triggering related information.

type: object

properties:

validityPeriod:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/DurationSec’

priority:

$ref: ‘#/components/schemas/Priority’

applicationPortId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Port’

appSrcPortId:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Port’

triggerPayload:

$ref: ‘TS29122_CommonData.yaml#/components/schemas/Bytes’

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’

DeliveryResult:

anyOf:

– type: string

enum:

– SUCCESS

– UNKNOWN

– FAILURE

– TRIGGERED

– EXPIRED

– UNCONFIRMED

– REPLACED

– TERMINATE

– 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: >

Possible values are

– SUCCESS: This value indicates that the device action request was successfully completed.

– UNKNOWN: This value indicates any unspecified errors.

– FAILURE: This value indicates that this trigger encountered a delivery error and is deemed permanently undeliverable.

– TRIGGERED: This value indicates that device triggering request is accepted by the SCEF.

– EXPIRED: This value indicates that the validity period expired before the trigger could be delivered.

– UNCONFIRMED: This value indicates that the delivery of the device action request is not confirmed.

– REPLACED: This value indicates that the device triggering replacement request is accepted by the SCEF.

– TERMINATE: This value indicates that the delivery of the device action request is terminated by the SCS/AS.

readOnly: true

Priority:

anyOf:

– type: string

enum:

– NO_PRIORITY

– PRIORITY

– 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: >

Possible values are

– NO_PRIORITY: This value indicates that the device trigger has no priority.

– PRIORITY: This value indicates that the device trigger has priority.