camaraproject / homedevicesqod Goto Github PK

API definition will be adapted as result of dicussions in CAMARA commonalities issue #101: camaraproject/WorkingGroups#101

Dears, I have a question over this API, may someone know the answer? Can app, the api caller, knows which router is the user's router? Or how should app know the devices that the user is allowed to adjust the bandwidth?

Update v0.1.0 API documentation according to v0.2.0 API version defintion.

Problem description
The current API only allows for policies to be applied to a single IP address. However, more homes are beginning to segment their networks and could have different WoD settings based on the subnet.

For instance, traffic on a home office subnet would be treated differently than a guest or IoT subnet.

Possible evolution
There are several approaches to solve this.

One is to replace the ipAddress property with networkCIDR

For IPv4, the would be a network address followed by a network mask. 192.168.1.0/24 or to specify a single IP 192.168.1.19/128

To preserve backwards compatibility, the API calls could be changed to:

oneOf:
  - ipAddress
  - networkCIDR

Alternative solution

Additional context

This issue shall define which issues are within scope of Home Devices QoD API for the Fall24 release.

**NOTE: In this particular case, a new 0.4.0 API version will be generated which is only intended to conform the existing 0.3.0 version to the Commonalities and ICM guidelines included in the CAMARA Fall24 meta-release. No new features are added.

Problem description

Update CODEOWERNS and MAINTAINERS.md as per points 3 and 7 of camaraproject/Governance#134
and ensure that all Maintainer and Codeowner have accepted the invite into the CAMARA GitHub organization.

Expected action

Create PR for the updates.
Review the current Maintainer list.

Additional context

Github templates for issues and pull requests to be configured for this repository.

https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Issue%20and%20PR%20template%20Howto.md

@rartych FYI.

Problem description
Generate release v0.2.0 from the current API version v0.2.0 in main branch. In current v0.2.0 API status there is no further functionality to be added. From release v0.2.0 will start the work to generate first stable API version v1.0.0 as per #39

Expected action

• PR to update CHANGELOG.md with v0.2.0 changes and to deprecate old API documentation once it has been embeded in the API specification in this version v0.2.0 as agreed in CAMARA Commonalities and as done in other API subprojects. See
  #18
• tag v0.2.0 creation for the last commit result of merging previous PR
• release v0.2.0 branch creation from that commit
• create release v0.2.0 for that tag/branch.

Additional context
N/A

Problem description
Generate release v0.3.0 from the current API version v0.3.0 in main branch.

Expected action

• PR to update CHANGELOG.md & README.md with v0.3.0 changes. This release aligns subproject and API spec with Commonalities v0.3.0 release. See #57 & #58.
• tag v0.3.0 creation for the last commit result of merging previous PR
• release v0.3.0 branch creation from that commit
• create release v0.3.0 for that tag/branch.

Additional context

API Design Guidelines Commonality recently approved in CAMARA: https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-design-guidelines.md

Addressed in PR #7

Problem description
how to use the camara’s api with my program?
for example, I want to get some informations from the home's modem. I will use the tr069 to get wifi info. now can i use camara’s api(HomeDevicesQoD) to implement it?

Upload first version of user stories doc in API documentation as agreed in 24/11 follow-up meeting.
https://github.com/camaraproject/HomeDevicesQoD/blob/main/documentation/MeetingMinutes/MOM-2022-11-24.md

Is anyone interested in joining the maintainers group? In case you are, please comment here.

Current Maintainers:
https://github.com/camaraproject/HomeDevicesQoD/blob/main/MAINTAINERS.MD

When looking at API documentation I have discovered that RFC 8325 provides QoS mapping between 802.11 UP (User Priority) and DSCP (Differentiated Services Code Point) - https://mrncciew.com/2021/09/14/rfc-8325-wifi-qos-mappings/

If the API is limited to WiFi downstream the then there are only 4 different service classes (Voice, Video, Best Effort & Background).
In the simple API these classes can be selected directly, but probably the API can be extended then the mapping to DSCP values according to RFC4594 needs to be used.

Can we reference RFC 8325 in the documentation as the standard reference for WiFi downstream ?

Adapt project to release/versioning guidelines agreed in Commonalities.
camaraproject/WorkingGroups#123

The next steps are expected to be

• PR to merge v0.1.0 changelog into the main branch.
• The merge commit from PR will be tagged as v0.1.0, and will get the v0.1.0 release branch.
• Merge the dev-v0.2.0 branch into main, so that it contains the latest stable API definition state as agreed (i.e. the ongoing status for API v0.2.0)
• Update README.md accordingly.

Problem description
The current API version v0.2.0 will be proposed as candidate to become v1.0.0 as the first stable API release. No further functionality will be added for the time being.

However, the requirements in order to generate a release v1.0.0 in CAMARA APIs is being discussed in Commonalities #139.

API Readiness minimum criteria checklist is defined in Commonalities in: https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-Readiness-Checklist.md

Step 5 ("API test cases and documentation") and Step 6 ("Tested by at least 2 operators") of the checklist are the ones under discussion. Regarding Step 5, there is another issue in commonalities #61 where test cases format is being discussed as well.

Expected action

• PR to create a "home_devices_qod_readiness_checklist.md" in https://github.com/camaraproject/HomeDevicesQoD/tree/main/documentation/API_documentation with the API readiness status as done in QualityOnDemand project
• Address remaining steps according to the conclusions of Commonalities issues mentioned above.

Additional context
N/A

CAMARA API design guidelines ( section 2.5) recommends to reduce the use of telco-specific terminolgy/acronyms in developer-facing APIs.
Although DiffServ is not telco-specific but rather low-level network-specific, I propose to reconsider:

• the name of the endpoint :
  /dscp
• the name of the property:
  dscp:
• the values of the property:

description: DSCP information for QoS
          enum:
            - CS0
            - CS1
            - AF11
            - AF12
            - AF13
            - CS2
            - AF21
            - AF22
            - AF23
            - CS3
            - AF31
            - AF32
            - AF33
            - CS4
            - AF41
            - AF42
            - AF43
            - CS5
            - EF
            - CS6
            - CS7
            - MAX_ALLOWED
          example: CS0

For values of DSCP property IETF RFC 4594 recommendations can be used to guide API users which value is the most relevant to their application:

    ------------------------------------------------------------------
   |   Service     |  DSCP   |    DSCP     |       Application        |
   |  Class Name   |  Name   |    Value    |        Examples          |
   |===============+=========+=============+==========================|
   |Network Control|  CS6    |   110000    | Network routing          |
   |---------------+---------+-------------+--------------------------|
   | Telephony     |   EF    |   101110    | IP Telephony bearer      |
   |---------------+---------+-------------+--------------------------|
   |  Signaling    |  CS5    |   101000    | IP Telephony signaling   |
   |---------------+---------+-------------+--------------------------|
   | Multimedia    |AF41,AF42|100010,100100|   H.323/V2 video         |
   | Conferencing  |  AF43   |   100110    |  conferencing (adaptive) |
   |---------------+---------+-------------+--------------------------|
   |  Real-Time    |  CS4    |   100000    | Video conferencing and   |
   |  Interactive  |         |             | Interactive gaming       |
   |---------------+---------+-------------+--------------------------|
   | Multimedia    |AF31,AF32|011010,011100| Streaming video and      |
   | Streaming     |  AF33   |   011110    |   audio on demand        |
   |---------------+---------+-------------+--------------------------|
   |Broadcast Video|  CS3    |   011000    |Broadcast TV & live events|
   |---------------+---------+-------------+--------------------------|
   | Low-Latency   |AF21,AF22|010010,010100|Client/server transactions|
   |   Data        |  AF23   |   010110    | Web-based ordering       |
   |---------------+---------+-------------+--------------------------|
   |     OAM       |  CS2    |   010000    |         OAM&P            |
   |---------------+---------+-------------+--------------------------|
   |High-Throughput|AF11,AF12|001010,001100|  Store and forward       |
   |    Data       |  AF13   |   001110    |     applications         |
   |---------------+---------+-------------+--------------------------|
   |    Standard   | DF (CS0)|   000000    | Undifferentiated         |
   |               |         |             | applications             |
   |---------------+---------+-------------+--------------------------|
   | Low-Priority  |  CS1    |   001000    | Any flow that has no BW  |
   |     Data      |         |             | assurance                |
    ------------------------------------------------------------------

Please note that QoD subproject defines only 4 values of QosProfile

enum:
       - QOS_E
       - QOS_S
       - QOS_M
       - QOS_L
     description: |
       * `QOS_E` - Qualifier for enhanced communication profile
       * `QOS_S` - Qualifier for the requested QoS profile _S_
       * `QOS_M` - Qualifier for the requested QoS profile _M_
       * `QOS_L` - Qualifier for the requested QoS profile _L_

Problem description
Formal inclusion of the GSMA OGW Product WS request to develop a Home Devices QoD service API

Possible evolution
N/A

Alternative solution
N/A

Additional context
This request just formalize the inclusion of this service as part of Open Gateway innitiative, no changes expected. Formal request includes original scope of the camara subgroup, with aligned/updated language. More details in the formal request file, attached
Camara Submission - HomeQoD_v2.docx

Problem description
Align subproject and API spec with Commonalities v0.3.0 release.

Possible evolution
Include all required changes such as linting ruleset, securitySchemes & scopes names, etc. Any changes that are ultimately applied will be listed in this issue and/or in the corresponding PR(s) for the record.

Alternative solution
N/A

Additional context
camaraproject/Commonalities#111

Align API spec format with the latest Commonalities agreements:

• Commonalities - adjust the error status field, which will eventually be an integer (not a patterned string): PR #145.
• Commonalities - adjust the schema references in the errors responses and apply the agreed solution: Issue #151 & PR #162.
• Commonalities - change the format of the API fields to lowerCamelCase: Issue #157, Discussion #169 & PR #171.

Upload first version of API documentation in API documentation.

camaraproject/WorkingGroups#120