Allignment on `maxAge` - behaviour for location-verification & location-retrieval

[maxl2287]

Problem description In location-retrieval it is described that the application throws a HTTP-422 if the requested maxAge does not fit with the freshness of the location provided by the network.

1. Issue

In location-retrieval there is still a HTTP-400 - Bad Request when the maxAge treshold cannot be satisfied: This example needs to be removed them: MaxAgeIssue as this conflicts with HTTP-422.

    RetrieveLocationBadRequest400:
      description: |-
        Problem with the client request. In addition to regular scenario of `INVALID_ARGUMENT`, another scenarios may exist:
          - maxAge threshold cannot be satisfied
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
             #...
            MaxAgeIssue:
              value:
                status: 400
                code: LOCATION_RETRIEVAL.MAXAGE_INVALID_ARGUMENT
                message: "maxAge threshold cannot be satisfied"

2. Issue

The behaviour of freshness is just described for location-retrieval. What about location-verification? There also the maxAge can be set and checks for the threshold. But here just HTTP-400 is provided and not HTTP-422.

Expected behavior

1. Cleanup the MaxAgeIssue example in location-retrieval
2. Add HTTP-422 - behavior for location-verification.

[bigludo7]

@maxl2287 Looking in the previous issue - here - I'm not sure we need to change something.

For location retrieval - we specified that 400 must be sent back if maxAge is syntactically wrong and 422 if the telco is unable to get the freshness required.

For location-verification not sure we need 422 as we have UNKNOWN result.

[maxl2287]

@bigludo7 I just want to make sure we're on the same page about the behavior we're discussing for the DeviceStatus APIs (https://github.com/camaraproject/DeviceStatus/issues/148#issuecomment-2168856215).

Do we really need to have a 200 - OK response with UNKNOWN as a result? I'm okay with using UNKNOWN, but if we do, we should think about why we want to use 422 for DeviceStatus instead of UNKNOWN.

[bigludo7]

@maxl2287 Fair point and I did not make the correlation with Device Status discussion.... We probably need to discuss this here. As we stated in Device Status when the network operator is not able to answer is probably better to answer 4xx than 2xx because:

• it explicitly indicates a failure to process the request due to some unknown network issue
• we should not charge for something that is not client's fault and 422 is easier to than 200

Adding @jlurien @alpaycetin74 @JoachimDahlgren to get their view !

[alpaycetin74]

hello, if the maxAge parameter is absent (maxAge=infinite), this is the most relaxed request the client can make with respect to age. In that case, if the server cannot still verify location, then there isn't one. I find it reasonable to return 200 with "UNKNOWN" in this case. 4XX means client error, and the client cannot do better than asking for infinite age.

If there is a maxAge parameter (including 0), but the system cannot satisfy the age requirement, yes 422 could be used. It would hint the client to try a different age, if possible. Please note in that case we lose the ability to return lastLocationTime as we will return an error body.

If you'd argue we should use the same behavior for all errors regarding age, then I am fine with using 422 in the infinite case as well.

[JoachimDahlgren]

Reading through the example uses of 422 in the API design guidelines it feels wrong to send a 422. In general 400 errors indicate that if the client modifies the request it will be able to get a 200 response. However in cases that the location is unknown that would not be the case. The example given in the work group meeting of a device roaming and we only have the cell-id and not a geographic location is rather a service issue.

Also a 422 "UNKNOWN" could be interpreted both as the device is unknown and location is unknown.