diff --git a/documentation/API_documentation/QoD_API.md b/documentation/API_documentation/QoD_API.md index 382ca6973f..ebdaa9b220 100644 --- a/documentation/API_documentation/QoD_API.md +++ b/documentation/API_documentation/QoD_API.md @@ -21,22 +21,22 @@ Before starting to use the API, the developer needs to know about the below spec 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. +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 +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 network operator for the user equipment **Identifier for the application server (AS)** IPv4 and/or IPv6 address of the application server (application backend) **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. +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 it 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. +Duration (in seconds) for which the QoS 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. @@ -81,30 +81,223 @@ Following table defines API endpoints of exposed REST based for QoD management o | **Endpoint** | **Operation** | **Description** | | -------- | --------- | ----------- | -| POST
\/qod/v0/sessions | **Create QoD Session** | Create QoS Session to manage latency/throughput priorities | -| GET
\/qod/v0/sessions/{sessionId} | **Query for QoD Session** | Querying for QoD session information details | -| DELETE
\/qod/v0/sessions/{sessionId} | **Delete QoD Session** | Deleting a QoD session | +| POST
\/qod/v0/sessions | **Create QoS Session Resource** | Create QoS Session to manage latency/throughput priorities | +| GET
\/qod/v0/sessions/{sessionId} | **Query for QoS Session Resource** | Querying for QoS session resource information details | +| DELETE
\/qod/v0/sessions/{sessionId} | **Delete QoS Session Resource** | Deleting a QoS session |
-#### QoD Create QoS Session Resource Operations - -| **Create QoD Session Resource** | -| -------------------------- | -| **HTTP Request**
POST \/qod/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]](#5) assigned by the Mobile network Operator for the user equipment. e.g. 123456789@domain.com
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](https://application-server.com/notifications)'
**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.** | -
- -#### QoD Query for QoS Session Resource - -| **Quering QoS Session Resource information** | -| --------------------------------------- | -| **HTTP Request**
GET\/qod-latency-api/v0/sessions/{sessionId}
**Query Parameters**
No query parameters are defined.
**Path Parameters**
sessionId: Session id that was obtained from the Create QoS Session operation.
**Request Body Parameters**
No request body parameters are defined.
**Response**

**200: Session information returned.**
Response body:
**ueId:** The identifier of the user equipment.
**asId:** The identifier of the application server.
**uePorts (optional):** The requested port(s) on the user equipment.
**asPort (optional):** The requested port(s) on the application server.
**qos:** Qualifier of the requested QoS profile.
**notificationUri (optional):** URI of the callback receiver.
**notificationAuthToken (optional):** Authentication token for callback API.
**id:** Session ID in UUID format.
**startedAt:** Timestamp of session start in seconds since Unix epoch.
**expiresAt:** Timestamp of session expiration if the session was not deleted in seconds since Unix epoch.

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

**Response**
**204:** Session deleted
**401:** Un-authorized.
**403:** Forbidden.
**404:** Session not found.
**503:** Service temporarily unavailable.| +#### QoD - Create QoS Session Resource Operations + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Create QoS Session Resource
HTTP RequestPOST <base-url>/qod/v0/sessions
Query ParametersNo query parameters are defined
Path ParametersNo path parameters are defined
Request Body Parametersduration (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 (MNO) for the user equipment. e.g. 123456789@domain.com
    • +
+

NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. 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]}
qosQualifier 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'
notificationAuthToken (optional)Authentication token for callback API, e.g. c8974e592c2fa383d4a3960714
Response200: 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
+ + +#### QoD - Query for QoS Session Resource + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Quering QoS Session Resource information
HTTP RequestGET <base-url>/qod/v0/sessions/{sessionId}
Query ParametersNo query parameters are defined
Path ParameterssessionIdSession id that was obtained from the Create QoS Session operation
Request Body ParametersNo request body parameters are defined
Response200: Session information returned + Response body:
+ ueId: The identifier of the user equipment
+ asId: The identifier of the application server.
+ uePorts (optional): The requested port(s) on the user equipment
+ asPort (optional): The requested port(s) on the application server
+ qos: Qualifier of the requested QoS profile
+ notificationUri (optional): URI of the callback receiver
+ notificationAuthToken (optional): Authentication token for callback API
+ id: Session ID in UUID format
+ startedAt: Timestamp of session start in seconds since Unix epoch
+ expiresAt: Timestamp of session expiration if the session was not deleted in seconds since Unix epoch +
401: Un-authorized
403: Forbidden
404: Session not found
503: Service temporarily unavailable
+ + +#### QoD - Delete QoS Session Resource + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Deleting QoS Session Resource
HTTP RequestDELETE <base-url>/qod/v0/sessions/{sessionId}
Query ParametersNo query parameters are defined
Path ParameterssessionIdSession ID that needs to be terminated
Request Body ParametersNo request body parameters are defined
Response204: Session deleted
401: Un-authorized
403: Forbidden
404: Session not found
503: Service temporarily unavailable
### 4.4 Errors