diff --git a/code/API_definitions/qod-api.yaml b/code/API_definitions/qod-api.yaml index 1bf2180471..eeb8572a9c 100644 --- a/code/API_definitions/qod-api.yaml +++ b/code/API_definitions/qod-api.yaml @@ -57,47 +57,59 @@ paths: $ref: "#/components/schemas/ErrorInfo" examples: Generic400: - summary: Schema validation failed + summary: Some parameter combinations or parameter values provided are not schema compliant value: status: 400 code: INVALID_ARGUMENT message: "Schema validation failed at ..." - PhoneNumberRequired: - summary: Phone number is required as part of device + DeviceMissing: + summary: Device must be specified value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: device.phoneNumber" - Ipv4AddressRequired: - summary: ipv4Address is required as part of device + message: "Expected property is missing: device" + InsufficientDeviceProperties: + summary: Device must be identified by at least one parameter value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: device.ipv4Address" - IpAddressRequired: - summary: Some IP address is required as part of device + message: "Insufficient properties specified: device" + InconsistentDeviceProperties: + summary: Device parameters provided identify different devices value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: device.ipv4Address or device.ipv6Address" - DevicePortsRequired: - summary: devicePorts is required + message: "Multiple inconsistent parameters specified: device" + CannotIdentifyDevice: + summary: No device can be identified from provided parameters value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: devicePorts" - QoSProfileRequired: - summary: qosProfile is required + message: "Unable to identify device from specified parameters: device" + InvalidDevicePublicPortValue: + summary: Invalid port specified for device public port + value: + status: 400 + code: OUT_OF_RANGE + message: "Invalid port value specified: device.ipv4Address.publicPort" + ApplicationServerMissing: + summary: Application server must be specified value: status: 400 code: INVALID_ARGUMENT - message: "Expected property is missing: qosProfile" - DevicePortsRangesNotAllowed: - summary: Ranges at devicePorts are not allowed + message: "Expected property is missing: applicationServer" + QoSProfileMissing: + summary: Required QoS profile must be specified value: status: 400 code: INVALID_ARGUMENT - message: "Ranges not allowed: devicePorts" + message: "Expected property is missing: qosProfile" + InvalidDevicePortsRanges: + summary: Invalid port ranges specified for devicePorts + value: + status: 400 + code: OUT_OF_RANGE + message: "Invalid port ranges specified: devicePorts" "401": $ref: "#/components/responses/Generic401" "403": @@ -223,6 +235,7 @@ components: type: string format: uuid description: Session ID in UUID format + SessionInfo: description: Session related information. allOf: @@ -253,6 +266,7 @@ components: type: array items: $ref: "#/components/schemas/Message" + CreateSession: description: Data type with attributes required for creating a session type: object @@ -276,6 +290,7 @@ components: $ref: "#/components/schemas/ApplicationServer" devicePorts: $ref: "#/components/schemas/PortsSpec" + description: The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports. applicationServerPorts: $ref: "#/components/schemas/PortsSpec" qosProfile: @@ -293,10 +308,12 @@ components: - device - applicationServer - qosProfile + Port: type: integer minimum: 0 maximum: 65535 + PortsSpec: type: object minProperties: 1 @@ -328,6 +345,7 @@ components: - 5070 description: | Ports may be specified as a list of ranges or single ports. + QosProfile: type: string enum: @@ -401,10 +419,11 @@ components: networkAccessIdentifier: $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: - $ref: "#/components/schemas/Ipv4Address" + $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: $ref: "#/components/schemas/Ipv6Address" - description: Device identifier + description: One or more parameters allocated to the device that allow it to be identified + ApplicationServer: type: object minProperties: 1 @@ -414,14 +433,49 @@ components: ipv6Address: $ref: "#/components/schemas/Ipv6Address" description: Application server identifier + NetworkAccessIdentifier: type: string example: "123456789@domain.com" + PhoneNumber: type: string pattern: '^\+?[0-9]{5,15}$' example: "123456789" - description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'. + description: Subscriber number (MSISDN) in E.164 format, starting with country code and optionally prefixed with '+'. + + DeviceIpv4Addr: + type: object + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + { + "publicAddress": "84.125.93.10", + "publicPort" : 59765 + } + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + + SingleIpv4Addr: + type: string + description: A single IPv4 address with no subnet mask + example: "84.125.93.10" + pattern: '^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$' + Ipv4Address: type: string format: ipv4 @@ -432,6 +486,7 @@ components: - address - an IPv4 number in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - address/mask - an IP number as above with a mask width of the form 1.2.3.4/24. In this case, all IP numbers from 1.2.3.0 to 1.2.3.255 will match. The bit width MUST be valid for the IP version. + Ipv6Address: type: string format: ipv6 @@ -447,6 +502,7 @@ components: - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 + Message: type: object properties: @@ -460,6 +516,7 @@ components: required: - severity - description + QosStatus: type: string enum: @@ -470,6 +527,7 @@ components: * `REQUESTED` - QoS has been requested by creating a session * `AVAILABLE` - The requested QoS has been provided by the network * `UNAVAILABLE` - The requested QoS cannot be provided by the network due to some reason + ErrorInfo: type: object required: diff --git a/documentation/API_documentation/QoD_API.md b/documentation/API_documentation/QoD_API.md index 44c72c536e..f756fb7a3b 100644 --- a/documentation/API_documentation/QoD_API.md +++ b/documentation/API_documentation/QoD_API.md @@ -27,7 +27,7 @@ Security access keys such as OAuth 2.0 client credentials used by client applica Latency or throughput requirements of the application mapped to relevant QoS profile class. **Identifier for the device** -At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier [[5]](#5) assigned by the mobile network operator for the device. +At least one identifier for the device (user equipment) out of four options: IPv4 address (either public IP address and port, or public and private IP address), IPv6 address, Phone number, or Network Access Identifier [[5]](#5) assigned by the mobile network operator for the device. **Identifier for the application server** IPv4 and/or IPv6 address of the application server (application backend) @@ -117,12 +117,12 @@ Following table defines API endpoints of exposed REST based for QoD management o

The identifier for the device (user equipment). The developer can choose to provide the below specified device identifiers:

-

NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device

+

NOTE: The MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST identify the same device

@@ -137,7 +137,7 @@ Following table defines API endpoints of exposed REST based for QoD management o devicePorts (optional) - A list of single ports or port ranges on the device,
e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]} + The ports used locally by the device for flows to which the requested QoS profile should apply. If omitted, then the qosProfile will apply to all flows between the device and the specified application server address and ports.
e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]} applicationServerPorts (optional) @@ -176,6 +176,9 @@ Following table defines API endpoints of exposed REST based for QoD management o 400: Invalid input + + 400: Out of range + 401: Un-authorized @@ -317,19 +320,22 @@ Following table provides an overview of common error names, codes, and messages | No | Error Name | Error Code | Error Message | | --- | ---------- | ---------- | ------------- | -|1 |400 | INVALID_INPUT | "Expected property is missing: device.msisdn" | -|2 |400 | INVALID_INPUT | "Expected property is missing: device.ipv4Address" | -|3 |400 | INVALID_INPUT | "Expected property is missing: device.ipv4Address or device.ipv6Address" | -|4 |400 | INVALID_INPUT | "Expected property is missing: devicePorts" | -|5 |400 | INVALID_INPUT | "Expected property is missing: qosProfile" | -|6 |400 | INVALID_INPUT | "Ranges not allowed: devicePorts" | -|7 |401 | UNAUTHORIZED | "No authorization to invoke operation" | -|8 |403 | FORBIDDEN | "Operation not allowed" | -|9 |404 | NOT_FOUND | "Session Id does not exist" | -|10 |409 | CONFLICT | "Another session is created for the same device" | -|11 |500 | INTERNAL | "Session could not be created" | -|12 |501 | NOT_IMPLEMENTED | "Service not implemented for the specified user device" | -|13 |503 | SERVICE_UNAVAILABLE | "Service unavailable" | +|1 |400 | INVALID_ARGUMENT | "Schema validation failed at ..." | +|2 |400 | INVALID_ARGUMENT | "Expected property is missing: device" | +|3 |400 | INVALID_ARGUMENT | "Insufficient properties specified: device" | +|4 |400 | INVALID_ARGUMENT | "Multiple inconsistent parameters specified: device" | +|5 |400 | INVALID_ARGUMENT | "Unable to identify device from specified parameters: device" | +|6 |400 | INVALID_ARGUMENT | "Expected property is missing: applicationServer" | +|7 |400 | INVALID_ARGUMENT | "Expected property is missing: qosProfile" | +|8 |400 | OUT_OF_RANGE | "Invalid port value specified: device.ipv4Address.publicPort" | +|9 |400 | OUT_OF_RANGE | "Invalid port ranges specified: devicePorts" | +|10 |401 | UNAUTHORIZED | "No authorization to invoke operation" | +|11 |403 | FORBIDDEN | "Operation not allowed" | +|12 |404 | NOT_FOUND | "Session Id does not exist" | +|13 |409 | CONFLICT | "Another session is created for the same device" | +|14 |500 | INTERNAL | "Session could not be created" | +|15 |501 | NOT_IMPLEMENTED | "Service not implemented for the specified user device" | +|16 |503 | SERVICE_UNAVAILABLE | "Service unavailable" | ### 4.5 Policies