Update qod api documentation to 0.8.0

[patrice-conil]

Fine by me

[ToshiWakayama-KDDI]

Hi, I raised some issues on Mapping table at the last QoD API meeting on 18th Nov, and it is supposed to be discussed by email discussion. I would like Herbert to start email discussion and the Mapping table in the API document should be reflected.
Thanks.

[tlohmar]

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.

From: Herbert Damker @.> Sent: Thursday, 1 December 2022 17:12 To: camaraproject/QualityOnDemand @.> Cc: Thorsten Lohmar @.>; Mention @.> Subject: Re: [camaraproject/QualityOnDemand] Update qod api documentation to 0.8.0 (PR #71)

@hdamker commented on this pull request.

---

In documentation/API_documentation/QoD_API.mdhttps://protect2.fireeye.com/v1/url?k=31323334-501cfaf3-313273af-454445554331-04c4a9c02fca10b7&q=1&e=135fed4c-b0dc-4db3-89c5-fa0a33018754&u=https%3A%2F%2Fgithub.com%2Fcamaraproject%2FQualityOnDemand%2Fpull%2F71%23discussion_r1037307981:

+### 4.3 Endpoint Definitions

+

+Following table defines API endpoints of exposed REST based for QoD management operations.

+

+| Endpoint | Operation | Description |

+| -------- | --------- | ----------- |

+| POST
\/qod-api/v0/sessions | Create QoD Session | Create QoS Session to manage latency/throughput priorities |

+| GET
\/qod-api/v0/sessions/{sessionId} | Query for QoD Session | Querying for QoD session information details |

+| DELETE
\/qod-api/v0/sessions/{sessionId} | Delete QoD Session | Deleting a QoD session |

+

+

+#### QoD Create QoS Session Operation

+

+| Create QoD Session |

+| -------------------------- |

+| HTTP Request
POST \/qod-api/v0/sessions
Query Parameters
No query parameters are defined.
Path Parameters
No path parameters are defined.
Request Body Parameters
duration (optional): Session duration in seconds. Maximal value of 24 hours is used if not set. e.g. 86400
ueId: The identifier for the user equipment(device). The developer can choose to provide the below specified user equipment identifiers:
- IPv4 address (supports mask) e.g. 192.168.0.1/24
- ipv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344
- msisdn (including country code and optionally could be prefixed by "+" sign) e.g. 004912345678923
- externalId [5] assigned by the Mobile network Operator for the user equipment. e.g. @.**@.>
NOTE: the communication service provider (CSP) might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different CSPs. In this case the identifiers MUST belong to the same UE
asId: The identifier used for application server. The developer can choose from the below application server identifiers:
- ipv4 address (supports mask) e.g. 192.168.0.1/24
- ipv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344
uePorts (optional): A list of single ports or port ranges on the user equipment.
e.g. "uePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}
asPorts (optional): A list of single ports or port ranges on the application server. e.g. "asPorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]}
qos: Qualifier for the requested latency/throughput profile. e.g. QOS_E
notificationUri (optional): URI of the callback receiver. Allows asynchronous delivery of session related events. e.g. 'https://application-server.com/notifications'<brhttps://application-server.com/notifications)'%3c/span%3e%3cbr> notificationAuthToken (optional): Authentication token for callback API. e.g. c8974e592c2fa383d4a3960714

Response
200: Session created
Response body:
duration: Session duration in seconds.
ueId: The identifier of the user equipment
asId: The identifer of the application server.
uePorts (optional): The requested port(s) on the user equipment.
asPorts (optional): The requested port(s) on the application server.
qos: Qualifier of the requested throughput profile.
notificationUri (optional): URI of the callback receiver.
notificationAuthToken (optional): Authentication token for callback API.
id: Session ID in UUID format.
e.g. 123e4567-e89b-12d3-a456-426614174000
startedAt: Timestamp of session start, in seconds since Unix epoch.
e.g. 1639479600
expiresAt: Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch. e.g. 1639566000

400: Invalid input.
401: Un-authorized.
403: Forbidden.
409: Conflict.
500: Server Error.
503: Service temporarily unavailable. |

@tlohmarhttps://protect2.fireeye.com/v1/url?k=31323334-501cfaf3-313273af-454445554331-19ce549c1a304140&q=1&e=135fed4c-b0dc-4db3-89c5-fa0a33018754&u=https%3A%2F%2Fgithub.com%2Ftlohmar Due to the long line I can not see what exactly you propose to change (we need to break the line going forward). Can you give a hint?

— Reply to this email directly, view it on GitHubhttps://protect2.fireeye.com/v1/url?k=31323334-501cfaf3-313273af-454445554331-04c4a9c02fca10b7&q=1&e=135fed4c-b0dc-4db3-89c5-fa0a33018754&u=https%3A%2F%2Fgithub.com%2Fcamaraproject%2FQualityOnDemand%2Fpull%2F71%23discussion_r1037307981, or unsubscribehttps://protect2.fireeye.com/v1/url?k=31323334-501cfaf3-313273af-454445554331-85f956b92a968e6f&q=1&e=135fed4c-b0dc-4db3-89c5-fa0a33018754&u=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FACKAQJ5TMZYVD77XZLYDSSLWLDE4XANCNFSM6AAAAAASEOJQIE. You are receiving this because you were mentioned.Message ID: @.**@.>>

[hdamker]

Hi, I raised some issues on Mapping table at the last QoD API meeting on 18th Nov, and it is supposed to be discussed by email discussion. I would like Herbert to start email discussion and the Mapping table in the API document should be reflected. Thanks.

@ToshiWakayama-KDDI Thanks for raising the issue with the mapping table which we will discuss as proposed. For the time being we deleted the copy of the table from the documentation and just kept the link.

[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.

[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).