Updating names qos-profile of endpoints

[RandyLevensalor]

What type of PR is this?

Add one of the following kinds:

• correction

What this PR does / why we need it:

Updates the endpoint names to include a verb.

Adds security scope to /retrieve-qos-profiles

Updates security scope on /retrieve-qos-profiles/{name}

Which issue(s) this PR fixes:

Fixes #345

Special notes for reviewers:

Should /retrieve-qos-profiles/{name} be singular /retrieve-qos-profile/{name} since it only returns a single qos-profile.

Changelog input

 release-note

Update qos-profile endpoint names to align with commonalites.  Updates the endpoint names to include a verb.

`/qos-profiles` is now `/retrieve-qos-profiles` and `/qos-profiles/{name}` is now `/retrieve-qos-profiles/{name}`

Additional documentation

This section can be blank.

docs

[hdamker]

@RandyLevensalor thanks for the PR!

I don't see a need to rename /qos-profiles/{name} as this is a GET and returns actually a qos-profile (and yes, nouns in the path always in plural, even if there is only a singular result). But maybe I'm wrong here ... @jlurien?

[eric-murray]

GET /qos-profiles/{name} is correct. qos-profiles is the name of the "resource" where we are looking for one named {name}. This is what developers familiar with "REST" APIs (I use the term loosely) will expect.

POST /retrieve-qos-profiles is a workaround resulting from Tim Berners-Lee's oversight in not making it sufficiently clear that GET requests may have a body, and that any proxy passing on a GET request must look for a body as well in case one is there. So a body could be defined for GET /qos-profiles to contain the filter parameters, but whether that body reaches the API gateway is not at all certain. Hence POST.

I'll be interested to see what developers' reaction to POST /retrieve-qos-profiles will be. If 3-legged tokens become "standard" for calling this API, or nobody want to filter by device, then it may yet be that we re-introduce GET /qos-profiles to keep them happy.

[hdamker]

I'll be interested to see what developers' reaction to POST /retrieve-qos-profiles will be. If 3-legged tokens become "standard" for calling this API, or nobody want to filter by device, then it may yet be that we re-introduce GET /qos-profiles to keep them happy.

Interesting enough it was your proposal to start the experiment (#318 (comment)) 😄 ... I agree that it might make sense to reintroduce GET /qos-profiles, making the returned list only dependent on the access token. But first of all we need to see if the API will be implemented at all broadly, or API Provider just offer a short list of "standard" profiles, agreed outside of the API.

[RandyLevensalor]

I'll be interested to see what developers' reaction to POST /retrieve-qos-profiles will be. If 3-legged tokens become "standard" for calling this API, or nobody want to filter by device, then it may yet be that we re-introduce GET /qos-profiles to keep them happy.

Interesting enough it was your proposal to start the experiment (#318 (comment)) 😄 ... I agree that it might make sense to reintroduce GET /qos-profiles, making the returned list only dependent on the access token. But first of all we need to see if the API will be implemented at all broadly, or API Provider just offer a short list of "standard" profiles, agreed outside of the API.

Agreed. Though now that we have the post, I'd like to explore some of the other filtering options including using an application profile from connectivity insight as a filter in the next release.

[eric-murray]

Agreed. Though now that we have the post, I'd like to explore some of the other filtering options including using an application profile from connectivity insight as a filter in the next release.

Yes, that is a good point. It is much simpler to pass complex objects in a request body than using query parameters. A good enough reason in itself to have the POST option.

[RandyLevensalor]

@camaraproject/quality-on-demand_codeowners I don't see any objections. Do you want to approve and merge?

[hdamker]

LGTM ... just a kind of question about the scope name for the operation, see my comment above.

[RandyLevensalor]

LGTM ... just a kind of question about the scope name for the operation, see my comment above.

Accepted the scope change. This resets the approval. Thanks!

[eric-murray]

I thought we were going to keep GET /qos-profiles/{name}. That would be the expected name for such an endpoint.

[eric-murray]

I don't see the need to have different scopes for the two endpoints. I'd suggest this endpoint also has scope qos-profiles:read.

[jlurien]

The original one was OK in line with the comment above

[hdamker]

I'm feeling guilty to have created some confusion here as I have overseen that @RandyLevensalor had renamed both endpoints, the POST /qos-profiles and the GET /qos-profiles/{name}, and then I had accidentally commented on the second one.

I agree here now with @eric-murray and @jlurien: the GET /qos-profiles/{name} should not be changed by this PR, as it is correct. Only the POST operation which is not creating a resource has to be renamed with a verb.

[hdamker]

Ready for Codeowner approvals.