Alignment of Device schema

[jlurien]

Problem description

The Device schema originally modeled in QoD WG, to identify the device, has been replicated in many other APIs. In the next release v0.10, there are some enhancements and corrections that are also applicable to the rest of APIs. Specifically, IP addresses have been remodeled so now single IP addresses are expected. Descriptions have been updated accordingly, and patterns have been removed.

Details: camaraproject/QualityOnDemand#230

Possible evolution

Review and align the model in other APIs that make use of it. You can check the latest version in QoD v0.10:

https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#L895 (line may change)

For DeviceIPv6Adddres, the sentence in description "The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts." only applies to QoD, so it has to be removed for other APIs.

[rartych]

Should we make an artifact in the repository containing this model definition as presented here?

    Device:
      description: |
        End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.

        The developer can choose to provide the below specified device identifiers:

        * `ipv4Address`
        * `ipv6Address`
        * `phoneNumber`
        * `networkAccessIdentifier`

        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.
      type: object
      properties:
        phoneNumber:
          $ref: "#/components/schemas/PhoneNumber"
        networkAccessIdentifier:
          $ref: "#/components/schemas/NetworkAccessIdentifier"
        ipv4Address:
          $ref: "#/components/schemas/DeviceIpv4Addr"
        ipv6Address:
          $ref: "#/components/schemas/DeviceIpv6Address"
      minProperties: 1

    PhoneNumber:
      description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'.
      type: string
      pattern: '^\+?[0-9]{5,15}$'
      example: "123456789"

    NetworkAccessIdentifier:
      description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
      type: string
      example: "[email protected]"

    DeviceIpv4Addr:
      type: object
      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.
      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

    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "84.125.93.10"

    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535

    DeviceIpv6Address:
      description: |
        The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

[gmuratk]

@rartych I think it will be good idea not just for Device schema, but also for other schemas that are used across multiple APIs.

[Kevsy]

Also to note that API Design Guidelines defines syntax style for path parameters and query parameters, but not for POST (non-URL) parameters.

This is especially relevant for Device Identifiers, as the Guidelines correctly state that POST should be used for sensitive data:

"The classification of data tagged as sensitive should be assessed for each API project, but might include the following examples:

• phone number (MSISDN) must be cautiously handled as it is not solely about the number itself, but also knowing something about what transactions are being processed for that customer
• localisation information (such as latitude & longitude) associated with a device identifier as it allows the device, and hence customer, location to be known
• physical device identifiers, such as IP addresses, MAC addresses or IMEI"

So the decision in this issue should trigger a new sub-section in the Guidelines (after section 3.4) to define syntax style for POST parameters.

[Kevsy]

Related to my comment above: a similar guidance is needed Device Identifiers are passed as HTTP Headers.

The POST or GET for transferring sensitive or complex data section of the API guidelines states:

"When using GET, transfer the data using headers, which are not routinely logged or cached"

Headers are typically Uppercase/hyphen-separated, and are documented that way in the HTTP Headers Definition section of the guidelines. Hence Device Identifier Headers would follow this convention:

IP-Address
Network-Access-Identifier
Phone-Number

[rartych]

@Kevsy Could you open a new issue for that?
This issue seems to be fixed by PR#107 and is going to be closed.

[Kevsy]

Done, #120

[rartych]

fixed by PR#107