camaraproject / qualityondemand Goto Github PK
View Code? Open in Web Editor NEWRepository to describe, develop, document and test the QualityOnDemand API family
Home Page: https://wiki.camaraproject.org/x/zwOeAQ
License: Apache License 2.0
Repository to describe, develop, document and test the QualityOnDemand API family
Home Page: https://wiki.camaraproject.org/x/zwOeAQ
License: Apache License 2.0
In the API spec currently we accept only 1 qos value for configuring the user session. In cases where qos configuration fails for various reasons, then the session would continue to use the default qos which might severally impact the application.
As supported in SCEF spec, we should introduce a new field named "fallbackQos" which will be used to configure the user session when the primary qos value requested for fails.
@emil-cheung proposed in PR #37 to introduce more detailed flow descriptions with an array of flowdescriptions of IpFlowDescriptions objects. It addresses the protocolIn/protocolOut parameter design issue (#32) and would allow asymmetric QoS flows (#36). Going forward it will also allow multiple flow descriptions as discussed in #13.
The PR wasn't merged as the proposed updated version of the simple QoD API (v0.8.0) #43 has solved issue #32 by omitting the parameters protocolIn and protocolOut, combined the previous two QoD APIs in one, and introduced other changes which require to rebase the proposed changes.
This issue is to preserve the proposal. Proposed YAML:
qos-stable-latency.yaml.txt
flowDescriptions within CreateSession schema:
flowDescriptions:
type: array
items:
$ref: '#/components/schemas/IpFlowDescription'
minItems: 1
maxItems: 2
IpFlowDescription:
type: object
required:
- direction
- protocol
- ueAddr
- uePorts
- remoteAddr
- remotePorts
properties:
direction:
$ref: '#/components/schemas/Direction'
protocol:
$ref: '#/components/schemas/Protocol'
ueAddr:
$ref: '#/components/schemas/Ipv4Addr'
uePorts:
$ref: '#/components/schemas/PortsSpec'
remoteAddr:
$ref: '#/components/schemas/Ipv4Addr'
remotePorts:
$ref: '#/components/schemas/PortsSpec'
As discussed within call on Friday Oct 21st:
The current API definition uses "in" and "out" to define flow direction (as in "protocolIn" and "protocolOut"), but these are relative terms and hence ambiguous. The UE would view "in" as the downlink and "out" as the uplink, whereas the AS would view "in" as the uplink and "out" as the downlink. And who know what a 3rd party API caller would think.
As UE and AS are explicitly identified in the API, I would suggest to define flow direction in terms of these actors to avoid any possibility of confusion. So "protocolIn" would become "protocolAStoUE" and "protocolOut" would become "protocolUEtoAS". And if the eminently sensible proposal in issue #32 to replace "protocolIn" and "protocolOut" with "protocol" and "direction" parameters is adopted, then the options for "direction" would be "UEtoAS", "AStoUE" and "BOTH".
See comments within PR #76
Originally posted by @jlurien in #76 (review)
As noted in MOM-2022-10-07.md the QoSProfile_Mapping_Table.md should be improved:
- The note should emphasize that it is just an example how the QoS Profiles can be mapped and not binding for operators.
- There is a notion that guranteed bit rate (GBR) can be offered only in limited scenarios (e.g. campus). The table is currently providing only examples for relative prioritization.
- Proposals for changed wording (e.g. "up to xx Mbit" replaced with more use case oriented wording) are welcome.
The current QoD API definitions identify the UE by its source IP address (ueAddr). If that address is public (i.e. routable) then knowledge of any UE source port (via the uePorts parameter) will allow the UE to be uniquely identified, albeit that this is not trivial. So if the specified UE source IP address is public, uePorts becomes a mandatory additional parameter.
But if the UE source IP address is private (i.e. non-routable), then it may not be possible to uniquely identify the UE. This is because the private address is allocated by the PDN GW to which the UE is connected, and a typical mobile network will have several of these with the specific PDN GW being selected based on network routing policies. PDN GWs will typically use the same private address space (usually the 10.0.0.0/8 range) which means that it is possible that more than one UE is currently allocated a given private IP address.
For the T8 interface, 3GPP resolve this ambiguity by requiring that an ipDomain parameter is also specified. This parameter resolves the ambiguity by identifying which PDN GW (i.e. which "domain") has allocated the private IP address. But I don't think CAMARA can adopt this solution as the API consumer is unlikely to know this information.
If the API consumer is the UE itself, then other approaches can be used to uniquely identify the UE, such as OpenID connect or the public source IP that will be seen by the API gateway even if not explicitly sent as an API parameter. And when the agreed proposal to allow use of GPSI as a UE identifier is implemented, then that can be specified rather than the UE source IP address.
But if the only identifying parameter for the UE is the private source IP address, then either a mechanism to resolve this ambiguity must be introduced by CAMARA, or the documentation should make clear that specifying a private IP for ueAddr is likely to result in an error response (probably 400 BAD REQUEST). Unfortunately I don't have a good proposal as to how this ambiguity can be resolved, so Vodafone's current position is that we will return an error message if the UE source IP specified is private.
Please see #7
A clear documentation for developers is needed what happens if requested QoS profile can not be provided by the network for the session, e.g. which QoS profile will be then be used for the session. Can be done together with #58
In CreateSession
, 400
error response the following example is provided.
UePortsRequired:
summary: uePorts is required
value:
code: INVALID_INPUT
message: "Expected property is missing: uePorts"
This meant to say that uePorts
is a required param. However, the CreateSession
definition mentiones uePorts
as optional param.
Which one is correct?
Same way in the below example, it is mentioned port ranges are not allowed for uePorts
. However, uePorts
is of type PortSpec
and there is no restriction on specifying ranges.
UePortsRangesNotAllowed:
summary: Ranges at uePorts are not allowed
value:
code: INVALID_INPUT
message: "Ranges not allowed: uePorts"
If these examples are not upto date, could we please remove them?
Loading the API into Swagger Editor, having an error :
As we have discussed during the calls, there is need to take a closer look at the parameter names used in the API spec with the objective of making the parameter names more developer friendly such that they can be understood by just going over the spec and would not require them to reference a separate document.
Example:
"asId" can be renamed to "applicationServerEndpoint"
This needs to be looked at high priority as changing the parameter names after initial release will impact backward compatibility.
QoD_Latency_Bandwidth_User_Story.md need to be updated and renamed according to updated qod-api.yaml
@MarkusKuemmerle @jordonezlucena @shilpa-padgaonkar
I have a quarkus/kotlin implementation to share with you ... Have you any path / hierarchy to suggest ?
Maybe a split by technology like quarkus / spring ?
Originally posted by @patrice-conil in camaraproject/WorkingGroups#63 (comment)
With the current definition of having two patterns in the "allOf"-definition of IPv6, the code-generator will generate a senseless Object of IPv6Addr, which cannot be used and which does not have anything relevant inside.
@Schema(name = "Ipv6Addr", description = "IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as: - address - The /128 subnet is optional for single addresses: - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 ")
@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2023-01-13T13:15:16.364985400+01:00[Europe/Berlin]")
public class Ipv6Addr {
@Override
public boolean equals(Object o) {
if (this == o) {
return true;
}
if (o == null || getClass() != o.getClass()) {
return false;
}
return true;
}
@Override
public int hashCode() {
return Objects.hash();
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("class Ipv6Addr {\n");
sb.append("}");
return sb.toString();
}
/**
* Convert the given object to string with each line indented by 4 spaces
* (except the first line).
*/
private String toIndentedString(Object o) {
if (o == null) {
return "null";
}
return o.toString().replace("\n", "\n ");
}
}
Means that IPv6 cannot be used as an input-variable at all.
Remove the allOf and just use one pattern which is the combination of both patterns.
Ipv6Addr:
type: string
format: ipv6
pattern: '(^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$)|(^((([^:]+:){7}([^:]+))|((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?))(\/.+)?$)'
example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
description: |
IPv6 address, following IETF 5952 format, may be specified in form <address/mask> as:
- address - The /128 subnet is optional for single addresses:
- 2001:db8:85a3:8d3:1319:8a2e:370:7344
- 2001:db8:85a3:8d3:1319:8a2e:370:7344/128
- address/mask - an IP v6 number with a mask:
- 2001:db8:85a3:8d3::0/64
- 2001:db8:85a3:8d3::/64
Contribution of the QoD-API spec v0.8.0
It contains following changes based on v0.1.0:
The existing yaml-files for latency and throughput should be removed.
The profile mapping file should be adjusted.
In https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-throughput.yaml#L41= a parameter is called notificationUrl
. In https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-throughput.yaml#L206= it is called notificationUri
. They should use the same name. The same applies to qos-stable-latency.yaml.
Dear "leading responsibles" for the CAMARA Sub Projects and Working Groups,
to have a clear view in which status each deliverable of CAMARA is we've defined a process "Changes and contributions to CAMARA".
The description of that process you can find in the https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md in the respective chapter.
That is the result of a discussion which has been started in the steering committee some weeks ago, I hope you can remember.
Now I would like to ask you to clean up "your" repository so that all issues, pull requests and files follow this process. In detail that means:
Hello team, we would like to understand reasons behinds few of the parameters in QoD API
Appreciate if someone can help provide answers to above ques
GET /sessions api call is missing a status field in its response body which would be used to indicate the current status of the qos session. This would be a very valuable piece of information for the developer and needs to be incorporated.
Add the possibility to send the SUCCESSFUL_RESOURCES_ALLOCATION event to notify that everything went as planned as discussed in #33
Is it not so sure that a developer would rather ask for a guaranteed low latency than a stable latency and a guaranteed bandwidth rather than a sable bandwidth? Using the term “stable” indicate a best effort scenario which is the starting point before asking for a specified QoD.
Would a developer be aware of the term App-Flow? I could interpret it as a “single UE” to App data flow. I could also interpret it as a “All UE” to App data flow. And what about UE-UE communication?
I can imagine two on-off cases. Either a time defined when the QoD is asked for (scenarios like a 15 min boost in gaming) or a turn on turn off ask in cases when a specific task needs to be performed (enhanced video quality during drone inspection work). Maybe it is better to have two user stories?
I would expect the enterprise to want to know the actual delivered latency and bandwidth. Maybe continues measurements or at least a notification if the requested quality is not met to be able to take actions on the application side (warn the user of the application or switch to a fallback procedures to not risk failures)
I feel we do not have the context of the stories around “decide later which package are ideally for billing”. Who is billing whom?
The user stories on making it possible for the developer to compare if it was good to spend money on QoD (as compared to just using best effort) seems a bit strange.
Currently the API spec does not have support for making any updates once the qos session is created.
Rather than assuming the data passed during session creation will always be static for the duration of the session, we need to consider use cases where either the UE details or the Application server details could change due to various factors and provide support for developers to make the updates via a PUT /sessions API.
Hello everyone,
When I implement a facade pattern in front of an API, I expect to be able to do it in a stateless way...just using mapping techniques
For our QOD API in front of SCEF this is not possible due to small design decisions.
-SessionInfo => AssessionWithQoSSubscription
OK
-NotificationData => QosChanged KO
Here the problem comes from the qod parameter that cannot be retrieved from NotificationData.
But the requestor must be able to match is initial request with the request id ... so I think we can remove it from QosChanged.
With these small modifications that don't impact functionalities IMHO we can implement stateless service that will be more efficient.
What do you think about?
Patrice
This includes:-
Questions/Comments are from Telefonica @jordonezlucena
Http "Internal server error" 500 is missing for GET & DELETE procedures.
Please let me know if you are happy for me to submit a PR for this.
As agreed previously in issue #3, please use the Commonalities User Story Template that has been just finalized to align the QoD User Stories with the Camara common template.
Callback api seems to use 'apikey' as a security mechanism but create session api defines 'notificationAuthToken' which is conflicting.
Either we should use only 'oAuth2ClientCredentials' or we should remove 'notificationAuthToken'- from create session api.
In current spec the error code 400 ("Bad Request") is used also for cases where the request is correct according to the spec but the implementation is not supporting certain parameter or is expecting other parameters then the API caller has provided.
We propose to introduce error code 501 "Not implemented" e.g. for valid UE identifiers which are not implemented.
The additional session-related fileds with respect to the ones already defined in CreateSession
should be part of the allOf
e.g. https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/
Change required is defined below:
SessionInfo:
allOf:
- $ref: '#/components/schemas/CreateSession'
- type: object
required:
- id
- duration
- startedAt
- expiresAt
properties:
id:
$ref: '#/components/schemas/SessionId'
startedAt:
type: integer
example: 1639479600
description: Timestamp of session start in seconds since unix epoch
format: int64
expiresAt:
type: integer
example: 1639566000
description: Timestamp of session expiration if the session was not deleted, in seconds since unix epoch
format: int64
description: Session related information.
This is actually relevant in our case because codegen tools are not properly generating the properties of SessionInfo with current definition.
To follow the versioning related guidelines agreed within commonalities working group, the QoD API version needs to be reset
This issue is to remind us of more network API specifications which have QoS support beyond the well-known NEF APIs.
We may need to revisit these specifications to see if we could refer to/reuse them.
3GPP TS 24.548 SEAL Network Resource Management
Unicast resource management can be used to modify QoS characteristics of a bear.
3GPP TS 23.558 Architecture for enabling Edge Applications
The EES API - Session with QoS provides an API to support QoS in an edge computing environment.
There was a discussion about the changes in QoSProfile_Mapping_Table.md in our last call, which were at that point of time already merged. The discussion was mainly about second example table which maps the same 4 QoS profiles from the current API spec to very different QoS characteristics.
The two main points received also in bilateral discussions were:
One proposal was to use different labels for the QoS profiles described in the second table. I suggest that it is too early now to extend already the list of QoS Profile labels (we rather have implementations for the ones defined in v0.8.0).
The proposal would be therefore to leave it for now with the four QoS Profile labels defined in v0.8.0 of the API definition, as it is too early to agree already on additional QoS profile labels. That would mean also to restrict QoSProfile_Mapping_Table.md again to one (the first) example table. Additional QoS Profile labels and it’s exemplary mapping can then be added together with following versions of the API.
Please reply to the discussion on the mailing list, comment here or on the related PR.
Current Camara QoD API does not have ”Flow Information” or “Flow Description” concepts that are in 3GPP NEF AsSessionWithQoS API. Instead, a parameterization approach is used, i.e., putting attributes such as “ueAddr”, “uePorts” etc. at the root level of the request data model, and expect the transformation layer to map them to “Flow Information”/”Flow Description”.
After evaluation, we see some limitations on this approach:
In https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#L43 a parameter is called notificationUrl
. In https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#L268 it is called notificationUri
. They should use the same name name notificationUrl
.
The example should also just contain the server reference without the /notifications
-endpoint (see https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qod-api.yaml#L271)
The code-generator will generate a class SessionNotificationsCallbackApi
.
Inside of this class it is already defined, that the endpoint /notifications
will be executed.
It will look like:
apiClient.invokeAPI("/notifications", HttpMethod.POST, Collections.<String, Object>emptyMap(), queryParams, postBody, headerParams, cookieParams, formParams, localVarAccept, localVarContentType, authNames, returnType);
The ApiClient will use the 'notificationUrl' from the notificationRequest here: https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_code/core/src/main/java/com/camara/qod/service/QodServiceImpl.java#L265
If the notificationUrl of the request will now be "https://application-server.com/notifications" then the application will post a notification against https://application-server.com/notifications/notifications
This Issue is an updated version of Issue 23.
While create a PR for #83, I noted that all the error responses in the spec that carry ErrorInfo
schema in the body should have the content type set to application/problem+json
instead of application/json
.
I decided to create this as a separate issue so that a PR release can be planned accordingly.
QoD_Stable_Bandwidth_API.md and QoD_Stable_Latency_API.md need to be consolidated into (new) QoD_API.md and updated according to updated qod-api.yaml
What if a client needs a QoS profile with LOW_LATENCY and THROUGHPUT_L?
To be able to compose these profiles, we would need to add an enum key that represents this combination and also a new key for all other relevant ones.
Instead, we could associate each profile with values based on the power of two (1, 2, 4, 8, 16...) and compose them via an OR operation. What do you think of this?
The current “protocolIn”/“protocolOut” parameters are confusing. Considering the IP protocols:
It is a bit confusing to specify different protocols in the same IP flow for different directions.
Currently there is no support for multiple ip flows in the Camara QoD Apis, so when constructing the corresponding NEF AfSessionWithQosSubscription parameters, which include a 'flowId', it is presumed that this will simply be set to something like '1'. However, considering the relevant 3gpp specifications it appears that the 'flowId' is in fact a tuple consisting of 16 bits for 'the media component number' and 16 bits for the 'ip flow number'. This issue is discussed in the attached pdf. If the analysis is correct, then, since media component numbers start from 1, we should in fact encode the 'flowId' as 0x00010001 (decimal 17). This may seem a trivial matter, but it underlying this is the fact that the internal internal southbound 3gpp APIs towards the PCF are highly expectant of ip flows being defined in the style of AF level SDP exchanges which detail media components and ip flows within them. This has implications for the evolution of the Camara APIs if and when they come to support multiple flows. There is an opportunity to inquire 3gpp about the structuring of the 'flowId' parameter (why not break the tuple out explicitly?) and also to inquire why it is that a single QosReference applies to all flows in a AfSessionWithQosSubscription, which is inconsistent with the equivalent southbound PCF API. Any existing insight on these matters within the Camara community would be of interest, prior to making such enquiries.
AfSessionWithQos.pdf.
The current API definitions require that the same QoS is applied to both the uplink and downlink, albeit that it can be applied to different protocols. For LOW_LATENCY, this is reasonable, as it is usually the round trip latency that is important. But for the throughput QoS profiles, this means the same throughput level (THROUGHPUT_L, THROUGHPUT_M or THROUGHPUT_S) must be applied to both the uplink and downlink. This imposes an unnecessary expense on the API consumer, who may only require the enhanced throughput in one direction.
To allow asymmetric QoS flows to be specified using the protocolIn and protocolOut parameters, a "NONE" option should be added to the Protocol schema enumerations. If the proposal in Issue #32 to replace "protocolIn" and "protocolOut" with "protocol" and "direction" is adopted, then this issue no longer arises as directional QoS levels can be specified using the relevant "direction" option (AStoUE, UEtoAS or BOTH).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.