diff --git a/TrafficSteeringApi.yaml b/TrafficSteeringApi.yaml index c0744e9824505989174d4bedf03ca336e893893c..8918dd570ecdadf33909fb6812d898e9c9e7de45 100644 --- a/TrafficSteeringApi.yaml +++ b/TrafficSteeringApi.yaml @@ -8,7 +8,7 @@ info: license: name: BSD-3-Clause url: https://forge.etsi.org/legal-matters - version: 2.2.1 + version: 3.1.1 servers: - url: https://localhost/mts/v1 paths: @@ -35,6 +35,8 @@ paths: $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' + '429': + $ref: '#/components/responses/429' parameters: [] /mts_sessions/{sessionId}: get: @@ -59,6 +61,8 @@ paths: $ref: '#/components/responses/404' '403': $ref: '#/components/responses/403' + '429': + $ref: '#/components/responses/429' parameters: - name: sessionId in: path @@ -135,9 +139,9 @@ paths: tags: - mts parameters: - - $ref: '#/components/parameters/Query.App_instance_id' - - $ref: '#/components/parameters/Query.App_name' - - $ref: '#/components/parameters/Query.Session_id' + - $ref: '#/components/parameters/Query.app_instance_id' + - $ref: '#/components/parameters/Query.app_name' + - $ref: '#/components/parameters/Query.session_id' responses: '200': description: Upon success, a response body containing an array of the MTS sessions is returned. @@ -153,6 +157,8 @@ paths: $ref: '#/components/responses/404' '403': $ref: '#/components/responses/403' + '429': + $ref: '#/components/responses/429' post: summary: Create a MTS session. description: This method is used to create a MTS session. This method is typically used in "Register application to the MTS Service" procedure as described in clause 6.2.7. @@ -228,22 +234,22 @@ components: items: $ref: '#/components/schemas/MtsAccessInfo' mtsMode: - description: 'Numeric value corresponding to a specific MTS operation supported by the TMS + description: 'Numeric value corresponding to a specific MTS operation supported by the TMS: - 0 = low cost, i.e. using the unmetered access network connection whenever it is available + 0 = low cost, i.e. using the unmetered access network connection whenever it is available. - 1 = low latency, i.e. using the access network connection with lower latency + 1 = low latency, i.e. using the access network connection with lower latency. - 2 = high throughput, i.e. using the access network connection with higher throughput, or/and multiple access network connection simultaneously if supported + 2 = high throughput, i.e. using the access network connection with higher throughput, or/and multiple access network connection simultaneously if supported. - 3 = redundancy, i.e. sending duplicated (redundancy) packets over multiple access network connections for highreliability and low-latency applications + 3 = redundancy, i.e. sending duplicated (redundancy) packets over multiple access network connections for highreliability and low-latency applications. - 4 = QoS, i.e. performing MTS based on the specific QoS requirements from the app' + 4 = QoS, i.e. performing MTS based on the specific QoS requirements from the app.' type: array - format: uint32 minItems: 1 items: - $ref: '#/components/schemas/Uint32' + type: integer + format: uint32 required: - mtsAccessInfo - mtsMode @@ -253,26 +259,26 @@ components: type: object properties: sessionId: - description: MTS session instance identifier + description: MTS session instance identifier. type: string timeStamp: $ref: '#/components/schemas/TimeStamp1' appInsId: - description: Application instance identifier + description: Application instance identifier. type: string appName: - description: Name of the application + description: Name of the application. type: string requestType: type: integer - description: 'Numeric value (0 - 255) corresponding to specific type of consumer as following: - - 0 = APPLICATION_SPECIFIC_MTS_SESSION - - 1 = FLOW_SPECIFIC_MTS_SESSION' enum: - 0 - 1 + description: 'Numeric value (0 to 255) corresponding to specific type of consumer as following: + + 0 = APPLICATION_SPECIFIC_MTS_SESSION. + + 1 = FLOW_SPECIFIC_MTS_SESSION.' flowFilter: type: array items: @@ -280,27 +286,33 @@ components: qosD: $ref: '#/components/schemas/QosD' mtsMode: - description: 'Numeric value (0 - 255) corresponding to a specific MTS mode of the MTS session: + description: 'Numeric value (0 to 255) corresponding to a specific MTS mode of the MTS session: - 0 = low cost, i.e. using the unmetered access network connection whenever it is available + 0 = low cost, i.e. using the unmetered access network connection whenever it is available. - 1 = low latency, i.e. using the access network connection with lower latency + 1 = low latency, i.e. using the access network connection with lower latency. - 2 = high throughput, i.e. using the access network connection with higher throughput, or multiple access network connection simultaneously + 2 = high throughput, i.e. using the access network connection with higher throughput, or multiple access network connection simultaneously. - 3 = redundancy, i.e. sending duplicated (redundancy) packets over multiple access network connections for high-reliability and low-latency applications + 3 = redundancy, i.e. sending duplicated (redundancy) packets over multiple access network connections for high-reliability and low-latency applications. - 4 = QoS, i.e. performing MTS based on the QoS requirement (qosD)' + 4 = QoS, i.e. performing MTS based on the QoS requirement (qosD).' type: integer format: uint32 + trafficSplit: + type: array + items: + $ref: '#/components/schemas/TrafficSplit' + trafficSwitch: + $ref: '#/components/schemas/TrafficSwitch' trafficDirection: description: 'The direction of the requested MTS session: - 00 = Downlink (towards the UE) + 00 = Downlink (towards the UE). - 01 = Uplink (towards the application/session) + 01 = Uplink (towards the application/session). - 10 = Symmetrical (see note)' + 10 = Symmetrical (see note).' type: string required: - appInsId @@ -310,66 +322,135 @@ components: - mtsMode - trafficDirection description: "|-\n NOTE:\tFor the downlink direction of a symmetrical flow, \"sourceIp\" and \"sourcePort\" in the \"flowFilter\" structure are used for source address and port, respectively; \"dstIp\" and \"dstPort\" are used for destination address and port, respectively. For the uplink direction of a symmetrical flow, \"sourceIp\" and \"sourcePort\" are used for destination address and port, respectively; \"dstIp\" and \"dstPort\" are used for source address and port, respectively." + BwChgEventSubscription: + x-etsi-ref: 7.3.2 + type: object + properties: + subscriptionType: + description: Shall be set to "BwChgEventSubscription". + type: string + callbackReference: + description: URI exposed by the client on which to receive notifications via HTTP. See note 1. + type: string + format: uri + websockNotifConfig: + description: Provides details to negotiate and signal the use of a Websocket connection between BWM and the service consumer for notifications. See note 1. + $ref: '#/components/schemas/WebsockNotifConfig' + _links: + $ref: '#/components/schemas/_links' + filterCriteria: + type: array + items: + $ref: '#/components/schemas/FilterCriteria' + required: + - subscriptionType + - filterCriteria + description: "|-\n NOTE 1:\tAt least one of callbackReference and websockNotifConfig shall be provided by the service consumer. If both are provided, it is up to BWM service to choose an alternative and return only that alternative in the response, as described in ETSI GS MEC 009 [6], clause 6.12a.\nNOTE 2:\tFor the case of session specific bw allocation, ueIp shall be used to identify subscription per UE per application." + SubscriptionLinkList: + x-etsi-ref: 7.3.3 + type: object + properties: + _links: + $ref: '#/components/schemas/_links1' + BwChgEventNotification: + x-etsi-ref: 7.4.2 + type: object + properties: + notificationType: + description: Shall be set to "BwChgEventNotification". + type: string + timeStamp: + $ref: '#/components/schemas/TimeStamp2' + dataVolDispersion: + type: array + items: + $ref: '#/components/schemas/DataVolDispersion' + _links: + $ref: '#/components/schemas/_links2' + required: + - notificationType + - dataVolDispersion + description: "|-\n NOTE:\tThe dataVolDispersion can be reported either as the total data volume of the session or periodically. dataVolDispersion shall provide information on data consumption per UE, in case of higher/lower data consumption, the service consumer can update the allocated bandwidth." + LinkType: + x-etsi-ref: 7.5.2 + type: object + properties: + href: + description: URI referring to a resource. + type: string + format: uri + required: + - href + WebsockNotifConfig: + x-etsi-ref: 7.5.3 + type: object + properties: + websocketUri: + description: Set by BWM service to indicate to the service consumer the web socket URI to be used for delivering notifications. + type: string + format: uri + requestWebsocketUri: + description: Set to TRUE by the service consumer to indicate that Websocket delivery is requested. + type: boolean TimeStamp: - description: Time stamp to indicate when the corresponding information elements are sent + description: Time stamp to indicate when the corresponding information elements are sent. type: object properties: seconds: - description: Time in seconds in Unix-time since January 1, 1970, 00:00:00 UTC + description: Time in seconds in Unix-time since January 1, 1970, 00:00:00 UTC. type: integer format: uint32 nanoSeconds: - description: Time in nanoseconds in Unix-time since January 1, 1970, 00:00:00 UTC + description: Time in nanoseconds in Unix-time since January 1, 1970, 00:00:00 UTC. type: integer format: uint32 required: - seconds - nanoSeconds MtsAccessInfo: - description: The information on access network connection as defined below + description: The information on access network connection as defined below. type: object - minItems: 1 properties: accessId: - description: Unique identifier for the access network connection + description: Unique identifier for the access network connection. type: integer format: uint32 accessType: - description: 'Numeric value (0-255) corresponding to specific type of access network as following: + description: 'Numeric value (0 to 255) corresponding to specific type of access network as following: - 0 = Unknown + 0 = Unknown. - 1 = Any IEEE802.11-based WLAN technology + 1 = Any IEEE802.11-based WLAN technology. - 2 = Any 3GPP-based Cellular technology + 2 = Any 3GPP-based Cellular technology. - 3 = Any Fixed Access + 3 = Any Fixed Access. - 11 = IEEE802.11 a/b/g WLAN + 11 = IEEE802.11 a/b/g WLAN. - 12 = IEEE 802.11 a/b/g/n WLAN + 12 = IEEE 802.11 a/b/g/n WLAN. - 13 = IEEE 802.11 a/b/g/n/ac WLAN + 13 = IEEE 802.11 a/b/g/n/ac WLAN. - 14 = IEEE 802.11 a/b/g/n/ac/ax WLAN (Wi-Fi 6) + 14 = IEEE 802.11 a/b/g/n/ac/ax WLAN (Wi-Fi 6). - 15 = IEEE 802.11 b/g/n WLAN + 15 = IEEE 802.11 b/g/n WLAN. - 31 = 3GPP GERAN/UTRA (2G/3G) + 31 = 3GPP GERAN/UTRA (2G/3G). - 32 = 3GPP E-UTRA (4G/LTE) + 32 = 3GPP E-UTRA (4G/LTE). - 33 = 3GPP NR (5G) ' + 33 = 3GPP NR (5G). ' type: integer format: uint32 metered: - description: 'Numeric value (0-255) corresponding to the following: + description: 'Numeric value (0 to 255) corresponding to the following: - 0: the connection is not metered (see note) + 0: the connection is not metered (see note). - 1: the connection is metered + 1: the connection is metered. - 2: unknown ' + 2: unknown. ' type: integer format: uint32 required: @@ -377,75 +458,189 @@ components: - accessType - metered TimeStamp1: - description: 'Time stamp to indicate when the corresponding information elements are sent ' + description: 'Time stamp to indicate when the corresponding information elements are sent. ' type: object properties: seconds: - description: The seconds part of the Time. Time is defined as Unixtime since January 1, 1970, 00:00:00 UTC + description: The seconds part of the Time. Time is defined as Unixtime since January 1, 1970, 00:00:00 UTC. type: integer format: uint32 nanoSeconds: - description: The nanoseconds part of the Time. Time is defined as Unix-time since January 1, 1970, 00:00:00 UTC + description: The nanoseconds part of the Time. Time is defined as Unix-time since January 1, 1970, 00:00:00 UTC. type: integer format: uint32 required: - seconds - nanoSeconds FlowFilter: - description: Traffic flow filtering criteria, applicable only if when requestType is set as FLOW_SPECIFIC_MTS_SESSION. Any filtering criteria shall define a single session only. In case multiple sessions match flowFilter, the request shall be rejected. If the flowFilter field is included, at least one of its subfields shall be included. Any flowFilter subfield that is not included shall be ignored in traffic flow filtering + description: Traffic flow filtering criteria, applicable only if when requestType is set as FLOW_SPECIFIC_MTS_SESSION. Any filtering criteria shall define a single session only. In case multiple sessions match flowFilter, the request shall be rejected. If the flowFilter field is included, at least one of its subfields shall be included. Any flowFilter subfield that is not included shall be ignored in traffic flow filtering. type: object - minItems: 1 properties: - sourceIp: - description: "Source address identity of session. The string for an IPv4 address shall be formatted in the \"dotted decimal\" notation as defined in IETF RFC\_1166\_[10]. The string for an IPv6 address shall be formatted according to clause 4 of IETF RFC\_5952\_[11], with in CIDR notation [12] used to provide the routing prefix" + sourceAddress: + description: "Source address identity of session. The string for an IPv4 address shall be formatted in the \"dotted decimal\" notation as defined in IETF RFC\_1166\_[10]. The string for an IPv6 address shall be formatted according to clause 4 of IETF RFC\_5952\_[11], with in CIDR notation IETF RFC 4632 [12] used to provide the routing prefix." type: string sourcePort: - description: 'Source port identity of session ' - type: integer - format: uint32 - dstIp: - description: "Destination address identity of session. The string for an IPv4 address shall be formatted in the \"dotted decimal\" notation as defined in IETF RFC\_1166\_[10]. The string for an IPv6 address shall be formatted according to clause 4 of IETF RFC\_5952\_[11], with in CIDR notation [12] used to provide the routing prefix" + description: 'Source port identity of session. ' + type: string + dstAddress: + description: "Destination address identity of session. The string for an IPv4 address shall be formatted in the \"dotted decimal\" notation as defined in IETF RFC\_1166\_[10]. The string for an IPv6 address shall be formatted according to clause 4 of IETF RFC\_5952\_[11], with in CIDR notation IETF RFC 4632 [12] used to provide the routing prefix." type: string dstPort: - description: Destination port identity of session - type: integer - format: uint32 + description: Destination port identity of session. + type: string protocol: - description: Protocol number + description: Protocol number. + type: string + maxSessions: + description: It indicates the maximum number of sessions MTS service will track for the given (sourceIp, dstIp etc.) provided by a service consumer. This attribute shall not be present in the request, but may be present in the response. type: integer format: uint32 dscp: - description: DSCP in the IPv4 header or Traffic Class in the IPv6 header + description: DSCP in the IPv4 header or Traffic Class in the IPv6 header. type: integer format: uint32 flowlabel: - description: Flow Label in the IPv6 header, applicable only if the flow is IPv6 + description: Flow Label in the IPv6 header, applicable only if the flow is IPv6. type: integer format: uint32 QosD: - description: QoS requirement description of the MTS session, applicable only if mtsMode = 4 (QoS). If the qosD field is included, at least one of its subfields shall be included. Any qosD subfield that is not included shall be ignored in Multi-access Traffic Steering (MTS) + description: "QoS requirement description of the MTS session, applicable only if mtsMode = 4 (QoS). If the qosD field is included, at least one of its subfields shall be included. Any qosD subfield that is not included shall be ignored in Multi-access Traffic Steering\_(MTS)." type: object properties: minTpt: - description: minimal throughput in [kbps] + description: Minimal throughput in [kbps]. $ref: '#/components/schemas/Unit32' - type: object maxLatency: - description: tolerable (one-way) delay in [10 nanoseconds] + description: Tolerable (one-way) delay in [10 nanoseconds]. $ref: '#/components/schemas/Unit32' - type: object maxLoss: - description: tolerable packet loss rate in [1/10^x] + description: Tolerable packet loss rate in [1/10^x]. $ref: '#/components/schemas/Unit32' - type: object maxJitter: - description: tolerable jitter in [10 nanoseconds] + description: Tolerable jitter in [10 nanoseconds]. $ref: '#/components/schemas/Unit32' - type: object priority: - description: 'numeric value (0 - 255) corresponding to the traffic priority: 0: low; 1: medium; 2: high; 3: critical' + description: 'numeric value (0 to 255) corresponding to the traffic priority: 0: low; 1: medium; 2: high; 3: critical.' $ref: '#/components/schemas/Unit32' - type: object + TrafficSplit: + description: Indicates the requested ratio between multiple access networks for the network aggregation required for higher throughput. This is based on the existing 3GPP ATSSS feature specified in clause 5.32.8 of ETSI TS 123 501 [i.5]. + type: object + properties: + accessId: + description: Unique identifier for the access network connection. + type: integer + format: uint32 + splittingRatio: + description: Splitting ratio for the access network as per the accessId. + type: string + required: + - accessId + - splittingRatio + TrafficSwitch: + description: "Priority based access network connection switching for seamless handover as per the application preference. This is based on the existing 3GPP ATSSS feature specified in clause\_5.32.8 of ETSI TS 123 501 [i.5]." + type: object + properties: + accessId: + description: Unique identifier for the access network connection. + type: integer + format: uint32 + required: + - accessId + _links: + description: Hyperlink related to the resource. This shall be only included in the HTTP responses and in HTTP PUT requests. + type: object + properties: + self: + description: Self-referring URI. The URI shall be unique within the BWM API as it acts as an ID for the subscription. + $ref: '#/components/schemas/LinkType' + required: + - self + FilterCriteria: + description: List of filtering criteria for the BW change event subscription. Any filtering criteria from below, which is included in the request, shall also be included in the response. + type: object + properties: + appInsId: + description: Application instance identifier. + type: string + ueIp: + description: Source address identity of session. See note 2. + type: string + required: + - appInsId + Subscriptions: + description: The service consumer's subscriptions. + type: object + properties: + href: + description: The URI referring to the subscription. + type: string + format: uri + subscriptionType: + description: Type of the subscription. The string shall be set according to the "subscriptionType" attribute of the associated subscription data type event defined in clause 7.3. + type: string + required: + - href + - subscriptionType + _links1: + description: List of hyperlinks related to the resource. + type: object + properties: + self: + description: URI of this resource. + $ref: '#/components/schemas/LinkType' + subscriptions: + type: array + items: + $ref: '#/components/schemas/Subscriptions' + required: + - self + TimeStamp2: + description: 'Time stamp to indicate when the corresponding + + information elements are sent.' + type: object + properties: + seconds: + description: 'The seconds part of the Time. Time is defined as + + Unix-time since January 1, 1970, 00:00:00 UTC.' + type: integer + format: uint32 + nanoSeconds: + description: 'The nanoseconds part of the Time. Time is defined as + + Unix-time since January 1, 1970, 00:00:00 UTC.' + type: integer + format: uint32 + required: + - seconds + - nanoSeconds + DataVolDispersion: + description: List of data volume dispersion information. + type: object + properties: + dataVol: + description: Sum of data volume (UL/DL) exchanged per UE per applications, ETSI TS 123 288 [i.4]. See note. + type: integer + format: uint32 + appInsId: + description: Application instance identifier. + type: string + ueIp: + description: Source address identity of session. + type: string + required: + - dataVol + - appInsId + _links2: + description: Link to resource related to this notification. + type: object + properties: + subscription: + description: A link to related subscription. + $ref: '#/components/schemas/LinkType' + required: + - subscription responses: '200': description: OK @@ -475,39 +670,45 @@ components: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' + '429': + description: 'Too Many Requests: used when a rate limiter has triggered.' + content: + application/problem+json: + schema: + $ref: '#/components/schemas/ProblemDetails' parameters: - Query.App_instance_id: + Query.app_instance_id: description: 'A MEC application instance may use multiple app_instance_ids as an input parameter to query the MTS session of a list of MEC application instances. app_instance_id corresponds to appInsId defined in table 7.2.5-1. See note.' name: app_instance_id in: query required: false - x-exportParamName: Query.App_instance_id + x-exportParamName: Query.app_instance_id schema: type: array items: type: string - Query.App_name: + Query.app_name: description: 'A MEC application instance may use multiple app_names as an input parameter to query the MTS session of a list of MEC application instances. app_name corresponds to appName defined in table 7.2.5-1. See note.' name: app_name in: query required: false - x-exportParamName: Query.App_name + x-exportParamName: Query.app_name schema: type: array items: type: string - Query.Session_id: + Query.session_id: description: 'A MEC application instance may use session_id as an input parameter to query the information of a list of MTS sessions. session_id corresponds to sessionId defined in table 7.2.5-1. See note.' name: session_id in: query required: false - x-exportParamName: Query.Session_id + x-exportParamName: Query.session_id schema: type: array items: