Skip to content

Commit

Permalink
Merge pull request #139 from eric-murray/main
Browse files Browse the repository at this point in the history 
Updated method for identifying devices by IPv4 address
  • Loading branch information
@hdamker
hdamker authored May 16, 2023
2 parents 3b4b013 + 2ff4b60 commit 8e0d2ea
Show file tree
Hide file tree
Showing 2 changed files with 106 additions and 42 deletions.
102 changes: 80 additions & 22 deletions code/API_definitions/qod-api.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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":
Expand Down Expand Up @@ -223,6 +235,7 @@ components:
type: string
format: uuid
description: Session ID in UUID format

SessionInfo:
description: Session related information.
allOf:
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -293,10 +308,12 @@ components:
- device
- applicationServer
- qosProfile

Port:
type: integer
minimum: 0
maximum: 65535

PortsSpec:
type: object
minProperties: 1
Expand Down Expand Up @@ -328,6 +345,7 @@ components:
- 5070
description: |
Ports may be specified as a list of ranges or single ports.
QosProfile:
type: string
enum:
Expand Down Expand Up @@ -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
Expand All @@ -414,14 +433,49 @@ components:
ipv6Address:
$ref: "#/components/schemas/Ipv6Address"
description: Application server identifier

NetworkAccessIdentifier:
type: string
example: "[email protected]"

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
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -460,6 +516,7 @@ components:
required:
- severity
- description

QosStatus:
type: string
enum:
Expand All @@ -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:
Expand Down
46 changes: 26 additions & 20 deletions documentation/API_documentation/QoD_API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -117,12 +117,12 @@ Following table defines API endpoints of exposed REST based for QoD management o
<td>
<p>The identifier for the device (user equipment). The developer can choose to provide the below specified device identifiers:</p>
<ul>
<li>ipv4Address: IPv4 address (supports mask) e.g. 192.168.0.1/24</li>
<li>ipv6Address: IPv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344</li>
<li>phoneNumber (including country code and optionally could be prefixed by "+" sign) e.g. 004912345678923</li>
<li>networkAccessIdentifier <a href="#5">[5]</a> assigned by the mobile network operator (MNO) for the device. e.g. [email protected]</li>
<li><b>ipv4Address</b>: Either public IPv4 address and port e.g. 84.125.93.10:59765, or public and private IPv4 addresses e.g. 84.125.93.10 & 192.168.0.1. The public IPv4 address alone is generally insufficient to identify the device. Subnet masks are not necessary or supported.</li>
<li><b>ipv6Address</b>: IPv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344</li>
<li><b>phoneNumber</b>: The device phone number, including country code and optionally prefixed by a "+" sign, e.g. 004912345678923</li>
<li><b>networkAccessIdentifier</b> <a href="#5">[5]</a> assigned by the mobile network operator (MNO) for the device. e.g. [email protected]</li>
</ul>
<p>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</p>
<p>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</p>
</td>
</tr>
<tr>
Expand All @@ -137,7 +137,7 @@ Following table defines API endpoints of exposed REST based for QoD management o
</tr>
<tr>
<td><b>devicePorts (optional)</b></td>
<td>A list of single ports or port ranges on the device,<br> e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}</td>
<td>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.<br> e.g. "devicePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}</td>
</tr>
<tr>
<td><b>applicationServerPorts (optional)</b></td>
Expand Down Expand Up @@ -176,6 +176,9 @@ Following table defines API endpoints of exposed REST based for QoD management o
<tr>
<td><b>400: Invalid input</b></td>
</tr>
<tr>
<td><b>400: Out of range</b></td>
</tr>
<tr>
<td><b>401: Un-authorized</b></td>
</tr>
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 8e0d2ea

Please sign in to comment.