search

camaraproject / DeviceLocation

Repository to describe, develop, document and test the DeviceLocation API family
Apache License 2.0
20 stars 31 forks source link

Semantics of the absence of 'maxAge' #184

Closed javier-carrocalabor closed 2 months ago

javier-carrocalabor commented 3 months ago

Problem description Regarding the usage of 'maxAge' parameter, we have use cases where "real-time" location is needed instead of an x-secs old location. Since 'maxAge' has a minimum value of 60 secs, using 'maxAge' is not a good way for a client to ask for such "real time" location verification. Our proposal is that not including the 'maxAge' parameter in the request (as it is optional) means that the client is requesting a verification of the "real time" location. I saw the same type of proposal in this issue, but there were no more explicit mentions to it in the maxAge issue. So, ¿is this the original meaning of not including 'maxAge' in the request?. In the case of real-time verification is requested in this way and it is not available, an 'UNKNOWN' response would be returned and a 'lastLocationTime' could be added if available. For us it is very important to be able to meet this kind of real-time requirement and, doing in this way, both requirements (real-time without 'maxAge' and lastKnownLocation using 'maxAge') could be met.

Expected action Alignment in the semantics of the spec definition.

jlurien commented 2 months ago

Another option would be to set the minimum for maxAge to 0, meaning that operator would try to locate the device in "real time"

alpaycetin74 commented 2 months ago

It could also be possible to use the parameter differently:

  1. Option 1:
  1. Option 2 (a bit more complicated, but this makes use of the current_or_last location feature of MLP).
    • maxAge of 0 is allowed in the API spec.
    • There is a new boolean parameter like "calculateNow" in the request, to indicate the client is requesting a fresh calculation.
    • If the system does not support it, or fresh location cannot be calculated at that time for any reason, evaluate maxAge: -- calculateNow = true and maxAge = 0: The client strictly wants to use a fresh location. The API response is unknown. -- calculateNow = true and maxAge is other than 0: The client requested a fresh location, but if it is not supported or unavailable, it will also accept a location with age <= maxAge -- calculateNow = true and maxAge parameter is not present: The client requested a fresh location, but if it is not supported or unavailable, it will also accept a location with any age.
javier-carrocalabor commented 2 months ago

Thank you, @alpaycetin74 I understand that adding the 'calculateNow' parameter is more "complete" somehow, but it adds a "reasoning overhead" for the clients and makes them have to be very careful when thinking what they are configuring in their request. So, thinking from the API clients perspective, I see "Option 1" simpler for them, as they just have to think how recent they need the location information to be. And I think that would be complete enough to meet the requirements of all scenarios. The worst case for Option 1 is that it doesn't consider the Option 2 case when calculateNow=true and maxAge>0. In this case, my understanding is that the clients should think what they really need for their use case. And, even so, in Option 1 they could retry if 'lastLocationTime' is returned when asking with maxAge=0 for this "corner case".

jlurien commented 2 months ago

It seems that makes sense to set the minimum for maxAge as 0. maxAge=0 would mean current, fresh location, that is, actively retrieved from the network at request time. In practice, this process may take some very few seconds to complete, so it would be no difference between maxAge=0 and maxAge=1

bigludo7 commented 2 months ago

Hello Option 1 works for me as well.

bigludo7 commented 2 months ago

@alpaycetin74 @jlurien One quick question before to propose the PR If we're not able to provide the location with the request freshness we send back:

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Unknown Location"
}

agreed?

javier-carrocalabor commented 2 months ago

@bigludo7 According to the 0.2.0 spec: https://github.com/camaraproject/DeviceLocation/blob/81278ecdbbecbfe9a723f53ce1f87358fd12be4d/code/API_definitions/location-verification.yaml#L16 I think the 'UNKNOWN' response would apply in your scenario.

alpaycetin74 commented 2 months ago

@alpaycetin74 @jlurien One quick question before to propose the PR If we're not able to provide the location with the request freshness we send back:

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Unknown Location"
}

agreed?

Hello, sorry for not responding earlier. In this case the result should be "unknown", I believe. A lastLocationTime may still be returned, if the system kept it from a previous calculation. I commented the same on the PR. Thank you.

bigludo7 commented 2 months ago

@javier-carrocalabor @alpaycetin74 Thanks - You're right for location-verification- I was thinking for location-retrieval but here we have the 400 maxAge threshold cannot be satisfied so not need to change here as well. Sorry for the confusion.