Skip to content

docs: improve info.description clarity in session-insights.yaml#80

Open
mohdfarhanakram wants to merge 1 commit intocamaraproject:mainfrom
mohdfarhanakram:fix/improve-description-clarity
Open

docs: improve info.description clarity in session-insights.yaml#80
mohdfarhanakram wants to merge 1 commit intocamaraproject:mainfrom
mohdfarhanakram:fix/improve-description-clarity

Conversation

@mohdfarhanakram
Copy link
Contributor

What type of PR is this?

correction

What this PR does / why we need it:

Improves the info.description and inline descriptions in session-insights.yaml to help API consumers understand the API correctly:

  • Changed "network operator" to "API provider" throughout (aligns with CAMARA terminology)
  • Changed "existing Application Profile" to "selected Application Profile" (obtained via GET application-profiles)
  • Removed unexpanded abbreviations: expanded RCA to "root cause analysis", WMM to "Wi-Fi Multimedia (WMM)"
  • Standardized "KPI metrics" to "KPIs" for consistency
  • Added "Session Identifiers" section clarifying the relationship between sessionId, id, and applicationSessionId
  • Added "Object Relationships" section describing cardinality (device → sessions, application → profiles)
  • Expanded the Authorization and Authentication section to explain how the device is linked to the API call via access token type
  • Expanded the error code section with common CAMARA error patterns and clearer guidance
  • Fixed leftover "QoS session" references to "Session Insights session" in RetrieveSessionsInput/Output

Which issue(s) this PR fixes:

Fixes #68

Special notes for reviewers:

Documentation and description changes only — no structural or functional changes to the API. All updates follow the changes listed in the issue.

Changelog input

Improved API descriptions for clarity: standardized terminology, expanded abbreviations, documented session identifiers and object relationships, and expanded authorization and error sections.

Additional documentation

N/A

- Create a monitoring session using an existing Application Profile.
- Send application-level KPIs (e.g., latency, jitter, throughput, loss) to the network operator.
- Receive a Session Insights Score reflecting network-evaluated session quality.
- Create a monitoring session using a selected Application Profile (obtained via GET application-profiles).
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
- Create a monitoring session using a selected Application Profile (obtained via GET application-profiles).
- Create a monitoring session using a selected Application Profile identifier (obtained via GET application-profiles).

@Kevsy
Copy link
Contributor

Kevsy commented Mar 23, 2026

Thanks @mohdfarhanakram , that's a really useful PR! One tiny suggestion made above, otherwise LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve API YAML info.description documentation clarity

2 participants