Initial yaml spec for device max bitrate

[maheshc01]

What type of PR is this?

Updates to address issue #10

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

Provide an initial proposed API specification.

Which issue(s) this PR fixes:

Fixes #10

[maheshc01]

@eric-murray . Tagging Eric as he has shared his inputs in the discussion #9 .
Look forward to everyone's inputs and thoughts on this.

I am unable to take part in the meeting series for this project as it is scheduled for 4 am my time.
Would it be possible to have the call at alternating time slots where 1 of it is US friendly time zone?

[maheshc01]

I would like to evaluate the options to make this API a candidate for Fall 25 release.
Looking forward for the thoughts from the team here so that i can plan the next steps on this.

[sachinvodafone]

As per commonalities:pre-release r3.1, we can follow the below

Generic401:
     description: Authentication problem with the client request
     headers:
       x-correlator:
         $ref: "#/components/headers/x-correlator"
     content:
       application/json:
         schema:
           allOf:
             - $ref: "#/components/schemas/ErrorInfo"
             - type: object
               properties:
                 status:
                   enum:
                     - 401
                 code:
                   enum:
                     - UNAUTHENTICATED
         examples:
           GENERIC_401_UNAUTHENTICATED:
             description: Request cannot be authenticated and a new authentication is required
             value:
               status: 401
               code: UNAUTHENTICATED
               message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required.

[sachinvodafone]

Generic429:
    description: Too Many Requests
    headers:
      x-correlator:
        $ref: "#/components/headers/x-correlator"
    content:
      application/json:
        schema:
          allOf:
            - $ref: "#/components/schemas/ErrorInfo"
            - type: object
              properties:
                status:
                  enum:
                    - 429
                code:
                  enum:
                    - QUOTA_EXCEEDED
                    - TOO_MANY_REQUESTS
        examples:
          GENERIC_429_QUOTA_EXCEEDED:
            description: Request is rejected due to exceeding a business quota limit
            value:
              status: 429
              code: QUOTA_EXCEEDED
              message: Out of resource quota.
          GENERIC_429_TOO_MANY_REQUESTS:
            description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached
            value:
              status: 429
              code: TOO_MANY_REQUESTS
              message: Rate limit reached.

[sachinvodafone]

we can put example

example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46". Commonalities have added an XCorrelator schema to CAMARA_common.yaml.

[eric-murray]

I would use the full endpoint name here, the logic being that, maybe one day an additional retrieve endpoint will be added, and if the scope needed to be renamed, that would be a breaking change. Using the full endpoint name ensures there will be no clashes or ambiguity in future.

Suggested change

	- media-rate:retrieve
	- media-rate:retrieve-max-media-rate

[eric-murray]

PhoneNumber schema was updated to require the leading +. See here.

[eric-murray]

Hi @maheshc01

Apologies for the delay in reviewing this. Preparing other APIs for the forthcoming meta-release has consumed most of my time recently.

I made some comments / suggestions, but this is fine as a "work in progress`, and non-compliance with Commonalities can be fixed later.

One change you need to make is to the filename, as this should not contain any version number. So should be media-rate.yaml (though see below, and consider media-streaming-rate.yaml).

A more general comment is on the naming. My thoughts are:

• "Media streaming" is a more descriptive, and probably better understood name than just "media". So name of API would be media-streaming-rate.
• The endpoint retrieve-max-media-rate is actually for the maximum downlink (downstream) media streaming rate, but this is only implicitly documented. Also, CAMARA doesn't like abbreviations! I'd suggest changing the name of the endpoint to retrieve-maximum-downstream-media-rate. Whilst a bit long, it has the advantage of being self-documenting.
• Additionally, I would add a new endpoint retrieve-maximum-upstream-media-rate to complete the set. Whilst not required for your use case, I can see that endpoint being requested. My view is that the implementation approach for both endpoints would be similar, but if you thought implementation of such a new endpoint would be problematic, you could define it as a separate API in a separate YAML.

On the documentation, I think that could be expanded to explain use of this API as a more general measure of device connection quality. So whilst one use case could indeed be rate adaption for media streaming, the maximum media streaming rate can also be used as a proxy for the general quality of the connection to the device. Again, the documentation can be updated at a later time.

[maheshc01]

ut this is fine as a "w

Hi @eric-murray ,

Thank you for your response and i can understand the focus required to get the fall 25 release through.
I was also busy with the release related activities.
I will go over the review comments you have made and start working on them.
As part of the changes i will also work on aligning it with the latest commonalities such that we have less effort involved when we want to plan for alpha release or spring26 release.

I was also considering to introduce an subscription /notification variation of the API, keeping it aligned with all the other Device status related APIs we have.
But for all these updates, I would like to have separate issues created and related PRs.
I will resolve the bulk of the review comments as part of this PR and for the ones which i feel additional time if required, i will create them as separate issues.

[maheshc01]

@eric-murray Update before the call today. Will prioritize to complete this before the next device status call.

[hdamker]

@maheshc01 Looking on the comments I assume that the name of the API will change. Please make sure that the filename will be exactly the api-name within the server URL (important for planned automation across the repositories) - it can still be changed, but consistently.

And then I have seen the URL https://github.com/camaraproject/MediaRate within the externalDocs object. Does that suggest to rename the repository for the purpose of the API? That could make sense, it would require an issue in API Backlog.

[maheshc01]

all the review comments have been addressed and additional issues have been created for tracking some of the open discussions points.
Please feel free to create more issues if i have missed something.
@eric-murray @sachinvodafone requesting your review and approval.

[hdamker]

Will close and reopen the PR to reset the linting check after #16

[hdamker]

All good from centralized megalinter perspective (the cancelled legacy check can be ignored).

[eric-murray]

Thanks @maheshc01

Looks good. Only one minor comment. Otherwise I'm happy to approve. Hopefully we agree to merge this at the next meeting.

[maheshc01]

are we good to merge the code?

[eric-murray]

are we good to merge the code?

I'm happy, and have approved. Just needs a codeowner to approve as well.

[maheshc01]

Thank for everyone's support in getting this PR reviewed and merged.

[maheshc01]

sorry.. I realized that the code is not merged yet and i am still waiting to get the maintainer role to be able to do it myself.
So, reopening the so that the changes can be merged.

[hdamker]

sorry.. I realized that the code is not merged yet and i am still waiting to get the maintainer role to be able to do it myself.
So, reopening the so that the changes can be merged.

@maheshc01 sorry for the delay, I haven't seen the update on your codeowners PR.

[maheshc01]

the PR has been reviewed and approved.
the code has been merged.
Closing the PR.