A.2 Resource representation and APIs for QoS session
24.5483GPPNetwork Resource Management - Service Enabler Architecture Layer for Verticals (SEAL)Protocol specificationRelease 17TS
A.2.1 SU_QosSessionManagement API
A.2.1.1 API URI
The CoAP URIs used in CoAP requests from SNRM-C towards the SNRM-S shall have the Resource URI structure as defined in clause C.1.1 of 3GPP TS 24.546 [31] with the following clarifications:
– The <apiName> shall be "su-nqs".
– The <apiVersion> shall be "v1".
– The <apiSpecificSuffixes> shall be set as described in clause A.2.1.2
A.2.1.2 Resources
A.2.1.2.1 Overview
Figure A.2.1.2.1-1: Resource URI structure of the SU_QosSessionManagement API
Table A.2.1.2.1-1 provides an overview of the resources and applicable CoAP methods.
Table A.2.1.2.1-1: Resources and methods overview
|
Resource name |
Resource URI |
CoAP method |
Description |
|
QoS Sessions |
/qos-sessions |
POST |
Create a new QoS session. |
|
GET |
Retrieve QoS sessions according to the query parameters. If there are no query parameters, do not fetch any QoS session. |
||
|
Individual QoS Session |
/qos-sessions/{qosSessionId} |
GET (NOTE) |
Retrieve an individual QoS session information according to query parameter on the resource identified by {qosSessionId}. If there are no query parameter, fetch the whole QoS session resource identified by {qosSessionId}. |
|
PUT |
Update an individual QoS session identified by {qosSessionId}. |
||
|
DELETE |
Delete a QoS session identified by {qosSessionId}. |
||
|
Individual QoS Session Participant |
/qos-sessions/{qosSessionId}/participants/{participantId} |
GET (NOTE) |
Retrieve QoS session participant information according to the query parameters. |
|
PUT |
Create or update QoS session participant information. |
||
|
DELETE |
Delete QoS session participant information. |
||
|
NOTE: The GET method can also be used to observe this resource. |
|||
A.2.1.2.2 Resource: QoS Sessions
A.2.1.2.2.1 Description
The QoS Sessions resource represents all the QoS sessions that are created at a given SNRM-S, or allows to create a new QoS session.
A.2.1.2.2.2 Resource Definition
Resource URI: {apiRoot}/su-nqs/<apiVersion>/qos-sessions
This resource shall support the resource URI variables defined in the table A.2.1.2.2.2-1.
Table A.2.1.2.2.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause C.1.1 of 3GPP TS 24.546 [31] |
|
apiVersion |
string |
See clause A.2.1.1 |
A.2.1.2.2.3 Resource Standard Methods
A.2.1.2.2.3.1 POST
This operation creates a QoS session at the SNRM-S.
This method shall support the request data structures specified in table A.2.1.2.2.3.1-1 and the response data structures and response codes specified in table A.2.1.2.2.3.1-2, and the response options specified in table A.2.1.2.2.3.1-3.
Table A.2.1.2.2.3.1-1: Data structures supported by the POST Request payload on this resource
|
Data type |
P |
Cardinality |
Description |
|
QosSession |
M |
1 |
Details of the QoS session that needs to be created, |
Table A.2.1.2.2.3.1-2: Data structures supported by the POST Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
QosSession |
M |
1 |
2.01 Created |
QoS session created successfully. |
|
NOTE: The mandatory CoAP error status codes for the GET Request listed in table C.1.3-1 of 3GPP TS 24.546 [31] shall also apply.. |
||||
Table A.2.1.2.2.3.1-3: Options supported by the 2.01 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Location-Path |
string |
M |
1 |
Contains the location path of the newly created resource relative to the request URI. It contains the qosSessionId segment of the complete resource URI according to the structure: {apiRoot}/su-nqs/<apiVersion>/qos-sessions/{qosSessionId} |
A.2.1.2.2.3.2 GET
This operation retrieves QoS sessions satisfying filter criteria.
This method shall support the URI query parameters specified in table A.2.1.2.2.3.2-1.
Table A.2.1.2.2.3.2-1: URI query parameters supported by the GET Request on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
qos-session-id |
string |
O |
0..1 |
Identifies a QoS session. |
|
val-service-id |
string |
O |
0..1 |
Identifies a VAL service. |
|
participant-id |
ValTargetUe |
O |
0..1 |
Identifies a VAL user or VAL UE to match a QoS session participant. |
This method shall support the request options specified in table A.2.1.2.2.3.2-2, the response data structures and response codes specified in table A.2.1.2.2.3.2-3, and the response options specified in table A.2.1.2.2.3.2-4.
Table A.2.1.2.2.3.2-2: Options supported by the GET Request on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Observe |
Uinteger |
O |
0..1 |
When set to 0 (Register) it extends the GET request to subscribe to the changes of this resource. When set to 1 (Deregister) it cancels the subscription. |
|
NOTE: Other request options also apply in accordance with normal CoAP procedures. |
||||
This method shall support the response data structures and response codes specified in table A.2.1.2.2.3.2 -3.
Table A.2.1.2.2.3.2-3: Data structures supported by the GET Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
array(QosSession) |
M |
0..N |
2.05 Content |
List of QoS sessions. This response shall include QoS sessions matching all the query parameters provided in the request. |
|
NOTE: The mandatory CoAP error status codes for the GET method listed in table C.1.3-1 of 3GPP TS 24.546 [31] also apply. |
||||
Table A.2.1.2.2.3.2-4: Options supported by the 2.05 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Observe |
Uinteger |
O |
0..1 |
Sequence number of the notification. |
|
NOTE: Other response options also apply in accordance with normal CoAP procedures. |
||||
A.2.1.2.3 Resource: Individual QoS Session
A.2.1.2.3.1 Description
The Individual QoS Session resource represents an individual QoS session that is created at the SNRM-S.
A.2.1.2.3.2 Resource Definition
Resource URI: {apiRoot}/su-nqs/<apiVersion>/qos-sessions/{qosSessionId}
This resource shall support the resource URI variables defined in the table A.2.1.2.3.2-1.
Table A.2.1.2.3.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause C.1.1 of 3GPP TS 24.546 [31] |
|
apiVersion |
string |
See clause A.2.1.1 |
|
qosSessionId |
string |
Represents an individual QoS session resource. |
A.2.1.2.3.3 Resource Standard Methods
A.2.1.2.3.3.1 GET
This operation retrieves QoS session information satisfying filter criteria.
This method shall support the URI query parameters specified in table A.2.1.2.3.3.1-1.
Table A.2.1.2.3.3.1-1: URI query parameters supported by the GET method on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
session-participants |
boolean |
O |
0..1 |
This is a content filtering flag. When set to "true", it indicates to the SNRM-S to include the participants of the QoS session. Set to "false" or omitted otherwise. |
|
session-configuration |
boolean |
O |
0..1 |
This is a content filtering flag. When set to "true", it indicates to the SNRM-S to include the configuration information of the QoS session. Set to "false" or omitted otherwise. |
This method shall support the request options specified in table A.2.1.2.3.3.1-2, the response data structures and response codes specified in table A.2.1.2.3.3.1-3, and the response options specified in table A.2.1.2.3.3.1-4.
Table A.2.1.2.3.3.1-2: Options supported by the GET Request on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Observe |
Uinteger |
O |
0..1 |
When set to 0 (Register) it extends the GET request to subscribe to the changes of this resource. When set to 1 (Deregister) it cancels the subscription. |
|
NOTE: Other request options also apply in accordance with normal CoAP procedures. |
||||
Table A.2.1.2.3.3.1-3: Data structures supported by the GET Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
QosSession |
M |
1 |
2.05 Content |
The QoS session information based on the request from the VAL server. This response shall include QoS session participants list if session-participants flag is set to "true" in the request, QoS session configuration information if the session-configuration flag is set to "true" in the request, or the whole QoS session resource if all the flags are omitted in the request. |
|
NOTE: The mandatory CoAP error status codes for the GET method listed in table C.1.3-1 of 3GPP TS 24.546 [31] also apply. |
||||
Table A.2.1.2.3.3.1-4: Options supported by the 2.05 Response Code on this resource
|
Name |
Data type |
P |
Cardinality |
Description |
|
Observe |
Uinteger |
O |
0..1 |
Sequence number of the notification. |
|
NOTE: Other response options also apply in accordance with normal CoAP procedures. |
||||
A.2.1.2.3.3.2 PUT
This operation updates the QoS session.
This method shall support the request data structures specified in table A.2.1.2.3.3.2-1 and the response data structures and response codes specified in table A.2.1.2.3.3.2-2.
Table A.2.1.2.3.3.2-1: Data structures supported by the PUT Request payload on this resource
|
Data type |
P |
Cardinality |
Description |
|
QosSession |
M |
1 |
Updated details of the QoS session. |
Table A.2.1.2.3.3.2-2: Data structures supported by the PUT Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
QosSession |
O |
0..1 |
2.04 Changed |
The QoS session updated successfully, and the updated QoS session may be returned in the response. |
|
NOTE: The mandatory CoAP error status codes for the PUT method listed in table C.1.3-1 of 3GPP TS 24.546 [31] shall also apply. |
||||
A.2.1.2.3.3.3 DELETE
This operation deletes the QoS session.
This method shall support the response data structures and response codes specified in table A.2.1.2.3.3.3-1.
Table A.2.1.2.3.3.3-1: Data structures supported by the DELETE Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
2.02 Deleted |
The individual QoS session is deleted. |
||
|
NOTE: The mandatory CoAP error status codes for the DELETE method listed in table C.1.3-1 1 of 3GPP TS 24.546 [31] shall also apply. |
||||
A.2.1.2.4 Resource: Individual QoS Session Participant
A.2.1.2.4.1 Description
The Individual QoS Session Participant resource represents an individual QoS session participant information that is maintained at the SNRM-S.
A.2.1.2.4.2 Resource Definition
Resource URI: {apiRoot}/su-nqs/<apiVersion>/qos-sessions/{qosSessionId}/participants/{participantId}
This resource shall support the resource URI variables defined in the table A.2.1.2.4.2-1.
Table A.2.1.2.3.2-1: Resource URI variables for this resource
|
Name |
Data Type |
Definition |
|
apiRoot |
string |
See clause C.1.1 of 3GPP TS 24.546 [31] |
|
apiVersion |
string |
See clause A.2.1.1 |
|
qosSessionId |
string |
Represents an individual QoS session resource. |
|
participantId |
ValTargetUe |
Identifies an individual QoS session participant. |
A.2.1.2.4.3 Resource Standard Methods
A.2.1.2.4.3.1 GET
This operation retrieves the individual QoS session participant’s information.
This method shall support the response data structures and response codes specified in table A.2.1.2.4.3.1-1.
Table A.2.1.2.4.3.1-1: Data structures supported by the GET Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
SessionParticipant |
M |
1 |
2.05 Content |
The QoS session participant information. |
|
NOTE: The mandatory CoAP error status codes for the GET method listed in table C.1.3-1 of 3GPP TS 24.546 [31] also apply. |
||||
A.2.1.2.4.3.2 PUT
This operation creates or updates the QoS session participant information.
This method shall support the request data structures specified in table A.2.1.2.4.3.2-1 and the response data structures and response codes specified in table A.2.1.2.4.3.2-2.
Table A.2.1.2.4.3.2-1: Data structures supported by the PUT Request payload on this resource
|
Data type |
P |
Cardinality |
Description |
|
SessionParticipant |
M |
1 |
New or updated information of the QoS session participant. |
Table A.2.1.2.4.3.2-2: Data structures supported by the PUT Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
SessionParticipant |
O |
0..1 |
2.01 Created |
The QoS session participant resource was created successfully, and the created resource may be returned in the response. |
|
SessionParticipant |
O |
0..1 |
2.04 Changed |
The QoS session participant resource was updated successfully, and the updated resource may be returned in the response. |
|
NOTE: The mandatory CoAP error status codes for the PUT method listed in table C.1.3-1 of 3GPP TS 24.546 [31] shall also apply. |
||||
A.2.1.2.4.3.3 DELETE
This operation deletes the QoS session participant information.
This method shall support the response data structures and response codes specified in table A.2.1.2.4.3.3-1.
Table A.2.1.2.4.3.3-1: Data structures supported by the DELETE Response payload on this resource
|
Data type |
P |
Cardinality |
Response codes |
Description |
|
n/a |
2.02 Deleted |
The QoS session participant resource is deleted. |
||
|
NOTE: The mandatory CoAP error status codes for the DELETE method listed in table C.1.3-1 1 of 3GPP TS 24.546 [31] shall also apply. |
||||
A.2.1.3 Data Model
A.2.1.3.1 General
This clause specifies the application data model supported by the API. Data types listed in clause C.1.4 of TS 24.546 [31] apply to this API.
Table A.2.1.3.1-1 specifies the data types defined specifically for the SU_QosSessionManagement API service.
Table A.2.1.3.1-1: SU_QosSessionManagement API specific Data Types
|
Data type |
Section defined |
Description |
Applicability |
|
QosSession |
A.2.1.3.2.2 |
QoS session details. |
|
|
SessionParticipant |
A.2.1.3.2.3 |
Represents membership and configuration details of the QoS session participant. |
|
|
ParticipantState |
A.2.1.3.2.4 |
Represents the state of the member in the group. E.g., an explicit member will register in the group by setting its "registered" attribute to "true", or will set that attribute to "false" when leaving the group. |
Table A.2.1.3.1-2 specifies data types re-used by the SU_QosSessionManagement API service.
Table A.2.1.3.1-2: Re-used Data Types
|
Data type |
Reference |
Comments |
Applicability |
|
GeographicalAreaId |
3GPP TS 24.546 [31] |
Identity of a geographical area. |
|
|
ScheduledCommunicationTime |
3GPP TS 24.546 [31] |
Represents a scheduled communication time. |
|
|
Uinteger |
3GPP TS 24.546 [31] |
Unsigned integer. |
|
|
Uri |
3GPP TS 24.546 [31] |
Unified resource identifier. |
|
|
ValTargetUe |
3GPP TS 24.546 [31] |
Used to identify either a VAL User or a VAL UE. |
A.2.1.3.2 Structured data types
A.2.1.3.2.1 Introduction
A.2.1.3.2.2 Type: QosSession
Table A.2.1.3.2.2-1: Definition of type QosSession
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
resUri |
Uri |
O |
0..1 |
The URI for the individual QoS session resource. (NOTE) |
|
|
requiredQoS |
string |
M |
1 |
End-to-end QoS requirements for the QoS session. |
|
|
participants |
array(SessionParticipant) |
M |
1..N |
List of participants of the QoS session. |
|
|
valServiceId |
string |
O |
1..N |
Identity of the VAL services enabled by the QoS session. |
|
|
serviceArea |
array(GeographicalAreaId) |
O |
1..N |
List of geographical area ids addressed by the QoS session. |
|
|
validPeriod |
ScheduledCommunicationTime |
O |
0..1 |
Indicates time period when the QoS session is valid. |
|
|
reportConf |
string |
O |
0..1 |
Reporting configuration for the active participants to report their QoS. |
|
|
NOTE: The "resUri" attribute is set by the SNRM-S and is not modifiable by the SNRM-C. |
|||||
A.2.1.3.2.3 Type: SessionParticipant
Table A.2.1.3.2.3-1: Definition of type SessionParticipant
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
resUri |
Uri |
O |
0..1 |
The URI of the individual QoS session participant resource. (NOTE) |
|
|
id |
ValTargetUe |
M |
1 |
This is a QoS session participant identity (VAL user ID or VAL UE ID) as per TS 23.434 [2]. |
|
|
state |
ParticipantState |
O |
0..1 |
Indicates the current state of the participant of the QoS session, e.g. it may indicate that the participant is active. When absent the state is unknown. |
|
|
reportedQoS |
string |
O |
0..1 |
QoS information reported by the participant. |
|
|
NOTE: The "resUri" attribute is set by the SNRM-S and is not modifiable by the SNRM-C. |
|||||
A.2.1.3.2.4 Type: ParticipantState
Table A.2.1.3.2.3-1: Definition of type ParticipantState
|
Attribute name |
Data type |
P |
Cardinality |
Description |
Applicability |
|
active |
boolean |
O |
0..1 |
Indicates if the participant is active in the QoS session, i.e. is actively reporting its QoS. When absent or "false" the participant is not active. |
A.2.1.4 Error Handling
General error responses are defined in clause C.1.3 of 3GPP TS 24.546 [31].
A.2.1.5 CDDL Specification
A.2.1.5.1 Introduction
The data model described in clause A.2.1.3 shall be binary encoded in the CBOR format as described in IETF RFC 8949 [rfc8949].
Clause A.2.1.5.2 uses the Concise Data Definition Language described in IETF RFC 8610 [30] and provides corresponding representation of the SU_QosSessionManagement API data model.
A.2.1.5.2 CDDL document
;;; QosSession
;;+ Represents a QoS Session.
QosSession = {
? resUri: Uri
requiredQoS: text ; QoS requirements for the QoS Session.
participants: [+ SessionParticipant]; The list of participants.
? valServiceId: text ; VAL service enabled by the QoS Session.
? serviceArea: [+ GeographicalAreaId]; The list of geographical area ids addressed by the QoS Session.
? validPeriod: ScheduledCommunicationTime
? reportConf: text ; Reporting configuration for the active participants of the QoS Session.
}
;;; SessionParticipant
;;+ Represents information of the QoS Session participant.
SessionParticipant = {
? resUri: Uri
id: ValTargetUe ; Identifies the participant of the QoS Session. Once set, this information cannot be updated.
? state: ParticipantState
? reportedQoS: text ; QoS information reported by the QoS Session participant.
}
;;; ParticipantState
;;+ Represents the state of the QoS Session participant.
ParticipantState = {
? active: bool
}
;;; GeographicalAreaId
;;+ Identifies a geographical area.
GeographicalAreaId = text
;;; ValTargetUe
;;+ Represents information identifying a VAL user ID or a VAL UE ID.
valUserId = {
valUserId: text ; Unique identifier of a VAL user.
}
valUeId = {
valUeId: text ; Unique identifier of a VAL UE.
}
ValTargetUe = valUserId / valUeId
;;; DayOfWeek
;;+ integer between and including 1 and 7 denoting a weekday. 1 shall indicate Monday, and the subsequent weekdays shall be indicated with the next higher numbers. 7 shall indicate Sunday.
DayOfWeek = 1..7
;;; TimeOfDay
;;+ String with format partial-time or full-time as defined in subclause 5.6 of IETF RFC 3339. Examples, 20:15:00, 20:15:00-08:00 (for 8 hours behind UTC).
TimeOfDay = text
;;; ScheduledCommunicationTime
;;+ Represents an offered scheduled communication time.
ScheduledCommunicationTime = {
? daysOfWeek: [1*6 DayOfWeek] ; Identifies the day(s) of the week. If absent, it indicates every day of the week.
? timeOfDayStart: TimeOfDay
? timeOfDayEnd: TimeOfDay
}
;;; Uri
;;+ string providing an URI formatted according to IETF RFC 3986.
Uri = text
A.2.1.6 Media Types
The media type for a QoS session shall be "application/vnd.3gpp.seal-qos-session-info+cbor".
The media type for a QoS session participant information shall be "application/vnd.3gpp.seal-qos-session-participant-info+cbor".
A.2.1.7 Media Type registration for application/vnd.3gpp.seal-qos-session-info+cbor
Type name: application
Subtype name: vnd.3gpp.seal-qos-session-info+cbor
Required parameters: none
Optional parameters: none
Encoding considerations: Must be encoded as using IETF RFC 8949 [17]. See "QosSession" data type in 3GPP TS 24.548 clause A.2.1.3.2.2 for details.
Security considerations: See Section 10 of IETF RFC 8949 [17] and Section 11 of IETF RFC 7252 [23].
Interoperability considerations: Applications must ignore any key-value pairs that they do not understand. This allows backwards-compatible extensions to this specification.
Published specification: 3GPP TS 24.548 "Network Resource Management – Service Enabler Architecture Layer for Verticals (SEAL); Protocol specification", available via http://www.3gpp.org/specs/numbering.htm.
Applications that use this media type: Applications supporting the SEAL network resource management procedures as described in the published specification.
Fragment identifier considerations: Fragment identification is the same as specified for "application/cbor" media type in IETF RFC 8949 [17]. Note that currently that RFC does not define fragmentation identification syntax for "application/cbor".
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): none
Macintosh file type code(s): none
Person & email address to contact for further information: <MCC name>, <MCC email address>
Intended usage: COMMON
Restrictions on usage: None
Author: 3GPP CT1 Working Group/3GPP_TSG_CT_WG1@LIST.ETSI.ORG
Change controller: <MCC name>/<MCC email address>
A.2.1.8 Media Type registration for application/vnd.3gpp.seal-qos-session-participant-info+cbor
Type name: application
Subtype name: vnd.3gpp.seal-qos-session-participant-info+cbor
Required parameters: none
Optional parameters: none
Encoding considerations: Must be encoded as using IETF RFC 8949 [17]. See "SessionParticipant" data type in 3GPP TS 24.548 clause A.2.1.3.2.3 for details.
Security considerations: See Section 10 of IETF RFC 8949 [17] and Section 11 of IETF RFC 7252 [23].
Interoperability considerations: Applications must ignore any key-value pairs that they do not understand. This allows backwards-compatible extensions to this specification.
Published specification: 3GPP TS 24.548 "Network Resource Management – Service Enabler Architecture Layer for Verticals (SEAL); Protocol specification", available via http://www.3gpp.org/specs/numbering.htm.
Applications that use this media type: Applications supporting the SEAL network resource management procedures as described in the published specification.
Fragment identifier considerations: Fragment identification is the same as specified for "application/cbor" media type in IETF RFC 8949 [17]. Note that currently that RFC does not define fragmentation identification syntax for "application/cbor".
Additional information:
Deprecated alias names for this type: N/A
Magic number(s): N/A
File extension(s): none
Macintosh file type code(s): none
Person & email address to contact for further information: <MCC name>, <MCC email address>
Intended usage: COMMON
Restrictions on usage: None
Author: 3GPP CT1 Working Group/3GPP_TSG_CT_WG1@LIST.ETSI.ORG
Change controller: <MCC name>/<MCC email address>