Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update qod api documentation to 0.8.0 #71

Merged
merged 39 commits into from
Dec 6, 2022
Merged

Update qod api documentation to 0.8.0 #71

Show file tree
Hide file tree
Changes from 38 commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
5df76af
Update and rename QoD_Stable_Latency_API.md to QoD_API.md
shilpa-padgaonkar Nov 15, 2022
5a44d51
Add files via upload
shilpa-padgaonkar Nov 15, 2022
9eccd6e
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
7699722
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
5572435
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
0b6addd
Add files via upload
shilpa-padgaonkar Nov 15, 2022
b10900b
Delete QoD_overview.PNG
shilpa-padgaonkar Nov 15, 2022
b5b95f3
Add files via upload
shilpa-padgaonkar Nov 15, 2022
13d9467
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
6f4098b
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
0256d6c
Update QoD_API.md
shilpa-padgaonkar Nov 15, 2022
4988cdf
Delete QoD_Stable_Bandwidth_API.md
shilpa-padgaonkar Nov 15, 2022
95df1ae
Update QoD_API.md
shilpa-padgaonkar Nov 17, 2022
91ddacb
Merge branch 'camaraproject:main' into shilpa-padgaonkar-qod-doc
hdamker Nov 17, 2022
16ee95e
Update QoD_API.md
shilpa-padgaonkar Nov 17, 2022
198acea
Update QoD_API.md
hdamker Nov 17, 2022
f2141e9
Update QoD_API.md
hdamker Nov 17, 2022
5c84946
Update QoD_API.md
shilpa-padgaonkar Nov 17, 2022
b4a294f
Update QoD_API.md
shilpa-padgaonkar Nov 17, 2022
7cae218
Update QoD_API.md
shilpa-padgaonkar Nov 17, 2022
9434d64
Update QoD_API.md
shilpa-padgaonkar Nov 18, 2022
68c1c62
Update documentation/API_documentation/QoD_API.md
shilpa-padgaonkar Nov 21, 2022
ece82ef
Update QoD_API.md
shilpa-padgaonkar Nov 21, 2022
5439ec0
changed qod-api to qod
shilpa-padgaonkar Dec 1, 2022
fa840e7
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
1327c73
update qos-session to qos-session-resource
shilpa-padgaonkar Dec 1, 2022
11cf10a
update qod-session to qod-session resource
shilpa-padgaonkar Dec 1, 2022
422c3f5
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
c4865a1
removed mapping table and just kept the link
shilpa-padgaonkar Dec 1, 2022
7f2ac6f
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
4a49703
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
fe0f022
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
f3f2cf0
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
d90c1f6
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
d3d72f4
Update documentation/API_documentation/QoD_API.md
hdamker Dec 1, 2022
64861cf
Update QoD_API.md
hdamker Dec 1, 2022
2d31e82
updated callflow pic
shilpa-padgaonkar Dec 1, 2022
e5ce872
Update documentation/API_documentation/QoD_API.md
hdamker Dec 2, 2022
1c8c8b4
Update documentation/API_documentation/QoD_API.md
hdamker Dec 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
172 changes: 172 additions & 0 deletions documentation/API_documentation/QoD_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# Overview

<span class="colour" style="color:rgb(0, 0, 0)">The Quality-On-Demand (QoD) API provides programmable interface for developers and other users (capabilities consumers) to request stable latency or throughput managed by Telco networks without the necessity to have an in-depth knowledge of the 4G/5G system or the overall complexity of the Telecom Systems [[1]](#1).</span>

## 1\. Introduction

Industrial (IoT), VR/Gaming, live video streaming, autonomous driving and many other scenarios demand network communication quality and are sensitive to any change in transmission conditions. Being able to request a stable latency (reduced jitter) or stable throughput from the network can improve user experience substantially.
hdamker marked this conversation as resolved.
Show resolved Hide resolved

The QoD API offers the application developers the capability to request for stable latency (reduced jitter) or throughput for some specified application data flows between application clients (within a User Equipment) and Application Servers (backend services). The developer has a pre-defined set of Quality of Service (QoS) Profiles which they could choose from depending on their latency or throughput requirements.

<img src="./resources/QoD_overview.PNG" alt="QoD_LM" title="QoD API Overview">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems that the Application data flows (between UE and Application Servers) are not passing through the telco network. I suggest to move the telco network illustration between the UE and the Application Servers.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, also the QoD API request is not necessarily triggered from the App Server

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tlohmar The network is actually not shown (only the backend system which offering the session recource)
@jlurien That's right but difficult to show without creating the impresson that both UE and AS have to communicate with the API.
Any proposal for a better illustration (not a formal correct picture) is appreciated.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I am giving it a stab. I think, it would be good to show the QoS session (between the UE application and the Application Server, going through a 5G System) and then the interaction between API invoker (e.g. the application server) and the QoD function.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tlohmar To get the updated documentation done for now, I suggest that you propose an updated picture in a minor editorial PR later.


## 2\. Quick Start

The usage of the API is based on QoS session resources, which can be created (based on available QoS profiles), queried and deleted.
The deletion of a requested session can be triggered by the API consumer or can be triggered automatically. The automatic process is triggered either when the requested specified duration of a QoS session has reached its limit or the default session expiration time has been reached (within an example provider implementation it is set to 24hrs).

Before starting to use the API, the developer needs to know about the below specified details:

**QOD service endpoint**
The URL pointing to the RESTful resource of the QoS API.

**Authentication**
Security access keys such as OAuth 2.0 client credentials used by Client applications to invoke the QoD API.

**QoS Profiles and QoS profile labels**
Latency or throughput requirements of the application mapped to relevant QoS profile class.

**Identifier for the the user equipment (UE)**
At least one identifier for the user equipment out of four options: IPv4 address, IPv6 address, MSISDN, or external ID [[5]](#5) assigned by the Mobile Operator for the user equipment

**Identifier for the application server (AS)**
IPv4 and/or IPv6 address of the application server (application backend)
hdamker marked this conversation as resolved.
Show resolved Hide resolved

**App-Flow (between the application client and application server)**
The precise application data flow the developer wants to prioritize and have stable latency or throughput for. This flow is in the current API version determined by the identifiers used for the user equipment and the application server. And can be further elaborated with details such as ports or port-ranges. Future version of the API might allow more detailed flow identification features.

**Duration**
Duration (in seconds) for which the QoD session (between application client and application server) should be created. This parameter is optional. When not specified, a default session duration (e.g. 24 hours) is applied. The user may request a termination before its expiration.

**Notification URL and token**
Developers may provide a callback URL on which notifications (eg. session termination) regarding the session can be received from the service provider. This is an optional parameter.

Sample API invocations are presented in Section 4.6.

## 3\. Authentication and Authorization
hdamker marked this conversation as resolved.
Show resolved Hide resolved

The QoD Service API makes use of the OAUTH 2.0 client credentials grant which is applicable for server to server use cases involving trusted partners
or clients without any protected user data involved.
In this method the API invoker client is registered as a confidential client with an authorization grant type of client_credentials [[3]](#3).

## 4\. API Documentation

### 4.1 API Version

0.8.0

### 4.2 Details

The usage of the QoD API is based on QoS profile classes and parameters which define App-Flows.
Based on the API, QoS session resources can be created, queried, and deleted. Once an offered QoS profile class is requested, application users get a prioritized service with stable latency or throughput even in the case of congestion. The QoD API has the following characteristics:

* A specified App-Flow is prioritized to ensure stable latency or throughput for that flow.
* The prioritized App-Flow is described by providing information such as user equipment (UE) IP address (or other UE identifier) & application server (AS) IP addresses and port/port-ranges.
* The developer can optionally specify the duration for which they need the prioritized App-flow.
* Stable latency or throughput is requested by selecting from the list of QoS profiles made available by the service provider (e.g. QOS_E) to map latency and throughput requirements.
* The developer can optionally also specify callback URL on which notifications for the session can be sent. <br>

Following diagram shows the interaction between different components

<br>

<img src="./resources/QoD_details.PNG" alt="QoD_LM" title="QoD Management API">
hdamker marked this conversation as resolved.
Show resolved Hide resolved

How QoS profiles are mapped to connectivity characteristics are subject to agreements between the communication service provider and the API invoker. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. [[2]](#2)


### 4.3 Endpoint Definitions

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

| **Endpoint** | **Operation** | **Description** |
| -------- | --------- | ----------- |
| POST<br> \<base-url>/qod/v0/sessions | **Create QoD Session** | Create QoS Session to manage latency/throughput priorities |
| GET<br> \<base-url>/qod/v0/sessions/{sessionId} | **Query for QoD Session** | Querying for QoD session information details |
| DELETE<br> \<base-url>/qod/v0/sessions/{sessionId} | **Delete QoD Session** | Deleting a QoD session |
<br>

#### QoD Create QoS Session Resource Operations

| **Create QoD Session Resource** |
| -------------------------- |
| **HTTP Request**<br> POST \<base-url>/qod/v0/sessions<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> No path parameters are defined.<br>**Request Body Parameters**<br> **duration (optional)**: Session duration in seconds. Maximal value of 24 hours is used if not set. e.g. 86400<br> **ueId:** The identifier for the user equipment(device). The developer can choose to provide the below specified user equipment identifiers:<br> - IPv4 address (supports mask) e.g. 192.168.0.1/24<br> - ipv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344<br> - msisdn (including country code and optionally could be prefixed by "+" sign) e.g. 004912345678923 <br> - externalId [[5]](#5) assigned by the Mobile network Operator for the user equipment. e.g. 123456789@domain.com <br>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<br> **asId:** The identifier used for application server. The developer can choose from the below application server identifiers: <br> - ipv4 address (supports mask) e.g. 192.168.0.1/24 <br> - ipv6 address (supports mask) e.g. 2001:db8:85a3:8d3:1319:8a2e:370:7344 <br> **uePorts (optional):** A list of single ports or port ranges on the user equipment.<br> e.g. "uePorts": {"ranges": [{"from": 5010,"to": 5020}],"ports": [5060,5070]} <br> **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]}<br> **qos:** Qualifier for the requested latency/throughput profile. e.g. QOS_E <br> **notificationUri (optional):** URI of the callback receiver. Allows asynchronous delivery of session related events. e.g. '[https://application-server.com/notifications](https://application-server.com/notifications)'</span><br> **notificationAuthToken (optional):** Authentication token for callback API. e.g. c8974e592c2fa383d4a3960714 <br><br>**Response**<br> **200: Session created**<br> Response body:<br> **duration:** Session duration in seconds.<br> **ueId:** The identifier of the user equipment <br> **asId:** The identifer of the application server.<br> **uePorts (optional):** The requested port(s) on the user equipment.<br> **asPorts (optional):** The requested port(s) on the application server.<br> **qos:** Qualifier of the requested throughput profile.<br> **notificationUri (optional):** URI of the callback receiver.<br> **notificationAuthToken (optional):** Authentication token for callback API.<br> **id:** Session ID in UUID format.<br> e.g. 123e4567-e89b-12d3-a456-426614174000<br> **startedAt:** Timestamp of session start, in seconds since Unix epoch.<br> e.g. 1639479600<br> **expiresAt**: Timestamp of session expiration if the session was not deleted, in seconds since Unix epoch. e.g. 1639566000 <br><br> **400:** **Invalid input.**<br> **401:** **Un-authorized. <br> **403:** Forbidden.**<br> **409:** **Conflict.**<br> **500:** **Server Error.**<br> **503:** **Service temporarily unavailable.** |
<br>

#### QoD Query for QoS Session Resource

| **Quering QoS Session Resource information** |
| --------------------------------------- |
| **HTTP Request**<br> GET\<base-url>/qod-latency-api/v0/sessions/{sessionId}<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> sessionId: Session id that was obtained from the Create QoS Session operation.<br>**Request Body Parameters**<br> No request body parameters are defined.<br>**Response**<br><br> **200: Session information returned.**<br> Response body:<br> **ueId:** The identifier of the user equipment.<br> **asId:** The identifier of the application server.<br> **uePorts (optional):** The requested port(s) on the user equipment.<br> **asPort (optional):** The requested port(s) on the application server.<br> **qos:** Qualifier of the requested QoS profile.<br> **notificationUri (optional):** URI of the callback receiver.<br> **notificationAuthToken (optional):** Authentication token for callback API.<br> **id:** Session ID in UUID format.<br> **startedAt:** Timestamp of session start in seconds since Unix epoch.<br> **expiresAt:** Timestamp of session expiration if the session was not deleted in seconds since Unix epoch.<br><br> **401:** Un-authorized. <br> **403:** Forbidden. <br> **404:** Session not found.<br> **503:** Service temporarily unavailable. |
<br>

#### QoD Delete QoS Session Resource

| **Deleting QoS session resource** |
| ---------------------------- |
| **HTTP Request**<br> DELETE\<base-url>/qod/v0/sessions/{sessionId}<br>**Query Parameters**<br> No query parameters are defined.<br>**Path Parameters**<br> sessionId: Session ID that needs to be terminated.<br>**Request Body Parameters**<br> No request body parameters are defined.<br><br>**Response**<br> **204:** Session deleted<br> **401:** Un-authorized. <br> **403:** Forbidden.<br> **404:** Session not found.<br> **503:** Service temporarily unavailable.|

### 4.4 Errors

Since CAMARA QoD API is based on REST design principles and blueprints, well defined HTTP status codes and families specified by community are followed [[4]](#4).

Details of HTTP based error/exception codes for the QoD API are described in Section 4.3 of each API REST based method.
Following table provides an overview of common error names, codes, and messages applicable to QoD API.

| No | Error Name | Error Code | Error Message |
| --- | ---------- | ---------- | ------------- |
|1 |400 | INVALID_INPUT | "Expected property is missing: ueId.msisdn" |
hdamker marked this conversation as resolved.
Show resolved Hide resolved
|2 |400 | INVALID_INPUT | "Expected property is missing: ueId.ipv4addr" |
|3 |400 | INVALID_INPUT | "Expected property is missing: ueId.ipv4addr or ueId.ipv6addr" |
Comment on lines +118 to +120
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator

@hdamker hdamker Dec 5, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

|4 |400 | INVALID_INPUT | "Expected property is missing: uePorts" |
|5 |400 | INVALID_INPUT | "Expected property is missing: qos" |
|6 |400 | INVALID_INPUT | "Ranges not allowed: uePorts" |
|7 |401 | UNAUTHORIZED | "No authorization to invoke operation" |
|8 |403 | FORBIDDEN | "Operation not allowed" |
|9 |404 | NOT_FOUND | "Session Id does not exist" |
|10 |409 | CONFLICT | "Another session is created for the same UE" |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: I thought that an API developer can create multiple QoD sessions with different Flow Descriptions (e.g. different ports) to the same device.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tlohmar Thanks for excellent observation ... need to be corrected with an issue and PR in the YAML first. What was actually meant (most probably) "There is an overlapping session existing for the same UE" ... but tbd.

|11 |500 | INTERNAL | "Session could not be created" |
hdamker marked this conversation as resolved.
Show resolved Hide resolved
|12 |503 | SERVICE_UNAVAILABLE | "Service unavailable" |

### 4.5 Policies

N/A

### 4.6 Code Snippets
<br>
<span class="colour" style="color:rgb(36, 41, 47)">Snippet 1, elaborates REST based API call with "*curl"* to create a QoS session for sample streaming service with following parameters: </span>

* QoS session with QoS-profile "QOS_E" mapping,
* App-Flow is specified for UE-Terminal identifier (ueId=2001:db8:85a3:8d3:1319:8a2e:370:7344), Application server identifier (asId=54.204.25.0/28) and Port number (asPorts=33001).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks complicated to have an IPv6 address as UE identifier and an IPv4 address as an Application Server Id. This may raise a bunch of technical questions.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest that it is an actual, even typical case: Let's assume that the mobile network is internally using only IPv6 (or only the IPv6 address is unique to identify the UE), and the application server is offering the service on IPv4 address. The mobile network is then using CGNAT. I agree that there are a several technical questions which need to be addressed (partly candidates for the FAQ section, partly open issue, e.g. #34).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean, the CGNAT is doing NAT64? I suggest to add some more description around the network assumptions. The Application Developers need to understand the concepts of the CAMARA QoD funtion.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tlohmar: as said, this is a perfect example for an FAQ. The challenge is that there is no general explanation possible as operator network implementation vary. Do you see how this can be done in a general FAQ entry here in CAMARA?


Please note, the credentials for API authentication purposes need to be adjusted based on target security system configuration.

| Snippet 1. Create QoS session resource |
| ----------------------------------------------- |
| curl -X 'POST' `https://sample-base-url/qod/v0/sessions` <br> -H 'accept: application/json' <br> -H 'Content-Type: application/json'<br> -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."<br> -d '{<br> "ueId": {"ipv6Addr": "2001:db8:85a3:8d3:1319:8a2e:370:7344"},<br> "asId": {"ipv4Addr": "54.204.25.0/28"},<br> "asPorts": "33001",<br> "qos": "QOS_E",<br> "notificationUri": `https://your-callback-server.com/notifications`,<br> "notificationAuthToken": "c8974e592c2fa383d4a3960714"<br> }' |
<br>
Snippet 2, elaborates sample QoS notification "SESSION_TERMINATION" message distributed from QoD backend to client callback function.

| Snippet 2. Sample QoS session notification |
| ------------------------------------------ |
| {<br> "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "event": "SESSION_TERMINATED"<br>} |

### 4.7 FAQ's

(FAQs will be added in a later version of the documentation)

### 4.8 Terms

N/A

### 4.9 Release Notes

N/A

## References

<a name="1">[1] 3GPP TS 23.501: System architecture for the 5G System (5GS); Stage 2 (Release 17), V17.4.0 (2022-03)<br>
<a name="2">[2] [CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/QoSProfile_Mapping_Table.md) <br>
<a name="3">[3] [CAMARA Commonalities : Authentication and Authorization Concept for Service APIs](https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Working/CAMARA-AuthN-AuthZ-Concept.md) <br>
<a name="4">[4] [HTTP Status codes spec](https://restfulapi.net/http-status-codes/) <br>
<a name="5">[5] [GPSI external identifier](https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/UE-Identification.md)
Loading