SED | OED | EAM | AED discovery operations: move device identifiers from request headers to request object

[Kevsy]

Problem description

As part of the Release Management review for SimpleEdgeDiscovery, TSC Chair @hdamker commented that SED uses request headers rather than a request object to pass device identifiers. Although that is supported by the current API design guidelines, SimpleEdgeDiscovery is the only stable CAMARA API using request headers for device identifiers. For consistency, SimpleEdgeDiscovery (SED), OptimalEdgeDiscovery (OED), EdgeApplicationManagement (EAM), ApplicationEndpointDiscovery (AED) should refactor any discovery operations requiring device identifiers from GET to POST.

Expected behavior

For Edge Cloud Zone discovery operations that require a device identifier:

1. Change the operation method from GET to POST.
2. Agree a new resource verb structure for the operation path resource name.
3. Agree the request device object, aiming for consistency across the APIs.
4. Create PRs of the YAML for each API.

For Edge Cloud Zone discovery operations that do not require a device identifier, we can keep GET /edge-cloud-zones

Alternative solution

Additional context

[Kevsy]

Updated following comment from @JoseMConde below

Suggested operation path resource names:

EAM: GET /edge-cloud-zones
returns an edge cloud zone array bounded to n members

SED: POST /retrieve-closest-edge-cloud-zone
returns an edge cloud zone array, bounded to a single member: the closest edge

OED: POST /retrieve-optimal-edge-cloud-zone (or /retrieve-optimal-edge-cloud-zones if more than one can be returned?)
returns an edge cloud zone array bounded to n members.

AED: POST /retrieve-closest-app-endpoint
returns the closest app endpoint (for discussion if that should be an array to allow for extensibility)

(note: the n 's are because an unbounded array represents a security risk)

Suggested request object for POST operations:

EAM:
No request object required to GET edge-cloud-zones

SED:
This will simply be a device identifier object as defined by Identity and Consent Management, e.g.

{
  "device": {
    "phoneNumber": "+123456789"
  }
}

OED:
For Optimal Edge Discovery, the API consumer should be able to also include criteria so the operator determine the 'optimal' response.

AED:
Similar to SED but also requires the appId

[JoseMConde]

Thanks @Kevsy , very interesting discussion, some thoughts:
Very good summary of the differents approach about GET and POST methods, for Application Endpoint Discovery should we have the same behaviour than SED??
About EAM, as I commented in the PR-326#326 (comment), I think could make sense to keep GET/edge-cloud-zones as It is and have the Discovery(Edge Cloud zone) method in OED. There is a comment #326 (comment) of @gainsley that explains the difference between the Discovery method and the method of EAM.

[Kevsy]

Thanks @JoseMConde -

for Application Endpoint Discovery should we have the same behaviour than SED??

Good point! Yes:, the operation should change from GET /apps-endpoints?filter=closest to POST retrieve-closest-app-endpoint, with the request body including a device object.

I think could make sense to keep GET/edge-cloud-zones as It is

Yes, I agree - it is an API call which does not involve sensitive request parameters

and have the Discovery(Edge Cloud zone) method in OED

Sure, that makes sense.

I've amended my comment above to reflect these points.

[gainsley]

I think the suggested approach outlined above by @Kevsy in #336 (comment) sounds great, I don't see any issues with it.

[gunjald]

Just a minor comment on naming convention followed is that typically any action oriented words like "retrieve" are suggested to be avoided as the HTTP method type GET, POST, PUT etc. are expected to play that role indicating the required action.

So it is just to explore if we need to stick to such practices as there are always exceptional cases where such practices can be relaxed as well depending upon the use case requirement.

[Kevsy]

Just a minor comment on naming convention followed is that typically any action oriented words like "retrieve" are suggested to be avoided as the HTTP method type GET, POST, PUT etc. are expected to play that role indicating the required action.

So it is just to explore if we need to stick to such practices as there are always exceptional cases where such practices can be relaxed as well depending upon the use case requirement.

@gunjald I agree there are arguments to be made either way, but it's part of API Design Guidelines, specifically:

"When the POST method is used:

• the resource in the path MUST be a verb (e.g. retrieve-location and not location) to differentiate from an actual resource creation"

[gunjald]

Just a minor comment on naming convention followed is that typically any action oriented words like "retrieve" are suggested to be avoided as the HTTP method type GET, POST, PUT etc. are expected to play that role indicating the required action.
So it is just to explore if we need to stick to such practices as there are always exceptional cases where such practices can be relaxed as well depending upon the use case requirement.

@gunjald I agree there are arguments to be made either way, but it's part of API Design Guidelines, specifically:

"When the POST method is used:

• the resource in the path MUST be a verb (e.g. retrieve-location and not location) to differentiate from an actual resource creation"

Thanks @Kevsy for the information and is very useful. I am aligned with the proposal.

[Kevsy]

Note SimpleEdgeDiscovery PR #78 includes the change, although I will make a separate PR to update the developer documentation once it is approved.