Update UeId definition in qod-api.yaml

[eric-murray]

• Separate fields introduced for private or public UE IP address in UeId object
• Require port to be additionally specified if UE is identified by its public IP address
• Require public IP address to be additionally specified if UE is identified by its private IP address
• Clean up of example error messages for 400 errors and introduction of additional error examples

[hdamker]

@jlurien @patrice-conil @sfnuser Would be great if you can review this PR from your point of view.

[emil-cheung]

When we talk about UE IP address, 'private' or 'public' sometimes are confusing.

First of all, 3GPP NEF AsSessionWithQos API accepts UE IP address assigned by 3GPP Core Network, it may be private or public, depends on NAT is deployed or not.

The Application Server communicates with the UE can observe the UE IP address and port from an IP connection (e.g., a TCP connection). The observed UE IP address shall be public (routable).

When there is not NAT, the assigned IP address and the observed IP address will be the same, and both of them are public. When there is NAT, the assigned IP address will be private and the observed IP address will be public.

We suggest using the terms as below inside UE ID:

• UE-assigned IP address or device-assigned IP address
• UE-observed IP address or device-observed IP address
• UE-observed port or device-observed port

[eric-murray]

@emil-cheung Irrespective of terminology, is your proposal that all three parameters should be specified if it is desired to identify the device by IPv4 address? Or is it your proposal that separate fields should be specified within the UeId object depending on whether the API caller wishes to identify the device by "device assigned" or "device observed" addresses?

Either way, it would have been useful to have that discussion within Issue #34 (open since August 5th 2022) rather than waiting until the PR is submitted.

To me, the definition of "private" address is clear. It is an address from the ranges defined within IETF RFC 1918 "Address Allocation for Private Internets". So if the API caller has an address for the device that is from within those ranges, then they are looking to identify the device using the private_ipv4_addr field. If it is not from those ranges, then they are looking to identify a device using the public_ipv4_addr field.

The advantage of having separate fields is that is reduces the number of parameters that the API caller needs to provide. However, I accept that giving the API caller choices can also be confusing. It would be good to have the opinion of those developers that might use this API.

If we cannot agree on whether that choice should be "public" / "private" or "device assigned" / "device observed", then my immediate thought is simply to mandate the specification of all three parameters when devices are to be identified by IPv4 address.

[hdamker]

There is a discussion paper from @emil-cheung for the topic, currently in #127. Let's have the discussion tomorrow in our regular call.

[eric-murray]

I think the discussion here is getting too complicated for a PR, so I'm closing this one and moving the discussion back to Issue #34. I have made an alternative proposal there. Once we have agreement in the issue, I will open a new PR - hopefully for approval and not as an invitation to re-open the discussion.