Update qod api documentation to 0.8.0

[shilpa-padgaonkar]

No description provided.

[patrice-conil]

Fine by me

[hdamker]

I think, it is the Error Codes e.g. 400 is Bad Request (not Invalid input). I don’t know, why it was not possible to comment on individual lines.

@tlohmar Thanks for the swift answer. I suppose that currently the documentation is correctly reflecting the error codes within the YAML (v0.8.0). Any further PRs should change the YAML and the documentation at the same time.

[hdamker]

Thanks a lot to @tlohmar for your extensive and detailed review. We have incorporated as many suggestions as possible and especially fixed the points where something was wrong on the documentation side.

There are some comments open:

• Some points which need first be proposed and discussed as changes to the API definition (e.g. error codes). The goal of this documentation update is to get consistent with version v0.8.0 of the API definition
• Other points need some more work and can be done independent of this update, e.g. a better illustration and adding FAQs

Said this, I propose that we try to merge this update as the base for further improvements
@tlohmar @jlurien @jpengar @eric-murray @patrice-conil @SyeddR @SylMOREL - would you approve?

[tlohmar]

Looks good. I dont have an "approve" button.

[eric-murray]

Errors 1, 2 & 3 don't make sense in the context of the UeId schema definition. The API definition requires that at least 1 UeId property is specified, but if the API caller has not specified any, how can we possibly know which one they have forgotten to specify? All we can say is that an insufficient number of properties have been specified, but we cannot say that a particular one is missing.

In addition, we need to consider:

• that more than one UeId property is specified, but they are inconsistent
• a property has been specified but is either not a valid value or is incorrectly formatted
• that the property (or properties) specified are valid but do not identify a valid UE or flow. For example, the MSISDN specified might not be a customer of the API provider. Or the public IP might not currently be in use.

[hdamker]

@eric-murray I agree that the error definition are not the right ones for all implementations. But:

1. The commented errors are currently the ones as examples within the YAML file. We should change them in both locations together (together with other error infos). I will open an issue for that and collect the respective comments.
2. Some of the errors can make sense depending on the implementation. E.g. if the communication service provider expects either ipv4addr or ipv6addr then he error 3 would make sense (it doesn't matter if there are further ones provided by the API invoker)

My proposal is that operators adapt this part according to their implementation for now.

[eric-murray]

@hdamker
OK, I agree that the documentation can be updated when the examples themselves are also updated. They are just examples, after all, not mandatory.

[jlurien]

Minor suggestion

[hdamker]

@tlohmar: you should have an approve button now (added you to the reviewers)
@eric-murray: can you check if my answer is ok for you?
@jlurien: have commited your suggestion

[jpengar]

@jlurien: have commited your suggestion

@hdamker thanks! ACK. Speaking on behalf of @jlurien (he is OOO this week).

[hdamker]

As far as I can see we are done and ready to merge this PR. Editorial PR to split the long line 99 will follow.