Skip to content

ISSUE-221 - Documentation review #237

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
deepakjaiswal1 merged 1 commit into from
Oct 11, 2026
Merged

ISSUE-221 - Documentation review #237

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,6 @@ _The above section is automatically synchronized by CAMARA project-administratio

* Find API reference documentation at folder: [code/API_definitions](code/API_definitions/)
* Find API testing documentation at folder: [code/Test_definitions](code/Test_definitions/)
* Find release status documentation at folder: [documentation/API_documentation](documentation/API_documentation)
* Find UML and complementary documentation at folder: [documentation/SupportingDocuments](documentation/SupportingDocuments)
* For other information refer to [Confluence CAMARA project wiki](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/14560817/WebRTC)

Expand Down
47 changes: 0 additions & 47 deletions code/API_definitions/README.MD
View file
Open in desktop

This file was deleted.

55 changes: 19 additions & 36 deletions code/API_definitions/webrtc-call-handling.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,39 +84,20 @@
You must check the webrtc-registration API to retrieve a valid registration
on the network that allows you to send calls (IMS registration).

Once this is completed, you can consume the POST /sessions/ endpoint to call
a remote destination.
Once this is completed, you can consume the `POST /sessions` endpoint to call
a remote destination. The request MUST include the local SDP `offer`.

```
POST /webrtc-call-handling/v0.2/sessions
{
"originatorAddress": "tel:+17085852753",
"receiverAddress": "tel:+17085854000",
}
```

This will create a call, but without local media you will have a problem, or
maybe the network will reject your call. You need to add a local SDP offer.

> **The WebRTC SDP local candidate**
> **The WebRTC SDP local offer**
>
> What is usually done, before attempt to create a call, is to solve the SDP local
description. This is, how you are going to send the media. To explain it briefly,
browsers offer the
[WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) that
include `getUserMedia()` and `RTCPeerConnection` interfaces that will simplify
the process.
>
> In summary, we need to obtain the media, create the `RTCPeerConnection`
and use it's SDP on our CAMARA webrtc-call-handling API as the offer. There
is extra information about this concept on the SupportingDocuments folder.

Once you retrieve you local SDP offer, you modify your session including it,
or maybe you prefer to solve the local candidate before attempt the call, in
that case, you will include your local offer on the audio/video session creation.
> Before creating a call, the client obtains its local SDP description, which
> describes how it is going to send the media. Browsers offer the
> [WebRTC API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API),
> including the `getUserMedia()` and `RTCPeerConnection` interfaces, to obtain
> the media and create the SDP offer. Extra information about this concept is
> available in the SupportingDocuments folder.

```
POST /webrtc-call-handling/v0.2/sessions
POST /sessions
{
"originatorAddress": "tel:+17085852753",
"receiverAddress": "tel:+17085854000",
Expand All @@ -127,10 +108,10 @@
```

Following this point, your call is progressing and the network will inform
about extra information required and connection status via de the
about extra information required and connection status via the
webrtc-events-subscriptions API.

Check webrtc-events-subscriptions API inline documentation and supporting documents
Check webrtc-events-subscriptions API inline documentation and Supporting Documents
for further information.

## 2. Hanging up a call
Expand All @@ -152,22 +133,22 @@
using the GET request, afterwards, you can present to the user some
confirmation option to accept the call.

Final step is to include a local offer. We already seen at 3.1 that a local
SDP is required, in this case, we will use the PUT request to modify the
audio/video session and include the information about the responding device.
Final step is to accept the call with the local SDP `answer`, using the PUT
request with status `Connected`.

Let's say that we are responding this session `0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD`:
```
PUT /webrtc-call-handling/v0.2/sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD/status
PUT /sessions/0AEE1B58BAEEDA3EABA42B32EBB3DFE0DEAD/status
{
"status": "InProgress",
"status": "Connected",
"answer": {
"sdp": "v=0\r\no=- 4808447918291752114 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE 0\r\na=extmap-allow-mixed\r\nm=audio 13765 UDP/TLS/RTP/SAVPF 111 63 9 0 8 13 110 126\r\nc=IN IP4 123.123.123.123\r\na=ice-ufrag:YoUo\r\na=ice-pwd:kK5J6IAgiKFDFU+2rC+FyZal\r\n...\r\n"
}
}
```

<!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->

# Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.
Expand All @@ -178,6 +159,7 @@
<!-- CAMARA:MANDATORY:additional-error-responses:END -->

<!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->

# Request body strictness

This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
Expand Down Expand Up @@ -209,6 +191,7 @@
- If `callType` is omitted, it defaults to `REGULAR`.

<!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->

# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
Expand Down Expand Up @@ -467,7 +450,7 @@
required: true
style: simple
explode: false
schema:

Check notice on line 453 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
pathParamMediaSessionId:
Expand All @@ -477,7 +460,7 @@
required: true
style: simple
explode: false
schema:

Check notice on line 463 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
x-correlator:
Expand All @@ -499,14 +482,14 @@
properties:
originatorAddress:
$ref: '#/components/schemas/Address'
originatorName:

Check notice on line 485 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: Friendly name of the call originator
example: 'Alice'
receiverAddress:
$ref: '#/components/schemas/Address'
receiverName:

Check notice on line 492 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: Friendly name of the call terminator
Expand Down Expand Up @@ -553,7 +536,7 @@
- $ref: '#/components/schemas/MediaSessionInformation'
- type: object
properties:
mediaSessionId:

Check notice on line 539 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: >-
Expand Down Expand Up @@ -586,7 +569,7 @@
present in a request from the application to the server to create a
session.
properties:
sdp:

Check notice on line 572 in code/API_definitions/webrtc-call-handling.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 65536
description: |-
Expand Down
64 changes: 32 additions & 32 deletions code/API_definitions/webrtc-events-subscriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,22 @@
description: |-
# Introduction

This API provide REST API for a client, browser or native application, to
receive events about updates of an active session or new sessions requests
(incoming calls) or registration termination.
The WebRTC Events Subscriptions API lets a client, browser or native
application, receive events about active session updates, new session
requests (incoming calls) and registration termination.

This API allows a WebRTC client to subscribe to events associated with a specific device,
identified by its `deviceId`. The deviceId uniquely represents a physical device on which
registrations and sessions may occur.
Subscriptions are bound to a specific device, identified by its `deviceId`,
which represents a unique physical device on which registrations and
sessions may occur.

Instead of requiring separate subscriptions per registration (`registrationId`) or per session
(`mediaSessionId`), event delivery is consolidated under the deviceId. This enables the client to
receive all relevant notifications — such as new call invitations or session status updates —
(`mediaSessionId`), event delivery is consolidated under the `deviceId`, so the client
receives all relevant notifications — such as new call invitations or session status updates —
for any registration or session belonging to the same device.

This allows the device applications to update the UI while media sessions
are progressing and also, allows the device to receive new session request,
generating incoming call scenarios for non-SIM devices.
As a result, device applications can update the UI while media sessions
progress, and receive new session requests, enabling incoming calls on
non-SIM devices.

A classic use case is the negotiation of a live media session (call), that
requires multiple asynchronous events from server side. Other classic
Expand Down Expand Up @@ -62,7 +62,7 @@
The CAMARA subscription model is detailed in the CAMARA API design guideline
document and follows CloudEvents specification.

This API allows to create an explicit notification channel for two types of
This API allows to create an explicit notification channel for three types of
events. It is mandatory in the subscription to provide the event type for
which the client would like to subscribe.

Expand Down Expand Up @@ -103,7 +103,7 @@
A `org.camaraproject.webrtc-events-subscriptions.v0.session-status` event includes
session information updates. With the same schema that is used with the
WebRTC Call Handling API, when retrieving information from the
`GET /webrtc-call-handling/session/{mediaSessionId}` endpoint.
`GET /webrtc-call-handling/sessions/{mediaSessionId}` endpoint.

In general lines, it is emitted each time that an event happens within the
subscribed session. This might happen when SDP updates are included for any
Expand Down Expand Up @@ -169,6 +169,7 @@
From a developer's point of view, reception of the `registration-ends` event should be treated as a signal to renew the WebRTC registration in order to continue receiving or initiating calls for the registered phone number.

<!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->

# Authorization and authentication

The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.
Expand All @@ -179,6 +180,7 @@
<!-- CAMARA:MANDATORY:authorization-and-authentication:END -->

<!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->

# Additional CAMARA error responses

The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.
Expand All @@ -189,6 +191,7 @@
<!-- CAMARA:MANDATORY:additional-error-responses:END -->

<!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->

# Request body strictness

This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
Expand Down Expand Up @@ -837,7 +840,7 @@
description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
example: qs15-h556-rt89-1298

RegistrationId:

Check notice on line 843 in code/API_definitions/webrtc-events-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: The unique identifier of the WebRTC registration.
Expand All @@ -849,7 +852,7 @@
- $ref: "../common/CAMARA_event_common.yaml#/components/schemas/CloudEvent"
- type: object
properties:
type:

Check notice on line 855 in code/API_definitions/webrtc-events-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 512
description: event-type that describes type of notification
Expand Down Expand Up @@ -921,7 +924,7 @@
pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'
maxLength: 256
example: 'tel:+11234567899'
originatorName:

Check notice on line 927 in code/API_definitions/webrtc-events-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: Friendly name of the call originator
Expand All @@ -932,7 +935,7 @@
pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'
maxLength: 256
example: 'tel:+11234567899'
receiverName:

Check notice on line 938 in code/API_definitions/webrtc-events-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
type: string
maxLength: 256
description: Friendly name of the call terminator
Expand Down Expand Up @@ -1591,10 +1594,11 @@
# Subscription examples
REGISTRATION_ENDS_SUBSCRIPTION:
description: |-
A sample of `registration-ends` subscription for registrationId
`+xsmcaum3z4zw4l0cu4w115m0` at `acme.opentelco.com`.
A sample of `registration-ends` subscription for a `deviceId` at
`acme.opentelco.com`.

This will be used to receive WebRTC registration termination events
for any registration of the device.
value:
protocol: HTTP
sink: https://notificationServer.opentelco.com
Expand All @@ -1610,20 +1614,16 @@
deviceId: "7d444840-9dc0-11d1-b245-5ffdce74fad2"
INVITE_SUBSCRIPTION:
description: |-
A sample of media `session-invitation` subscription for phone number
`+1234567890` at `acme.opentelco.com`.
A sample of media `session-invitation` subscription for a `deviceId`
at `acme.opentelco.com`.

This will be used to receive incoming sessions (incoming
calls). The implicit subscription to `subscription-ended` will make
the client aware of registration status updates from the server.
(i.e. when a REGISTRATION expires).
This will be used to receive incoming sessions (incoming calls) for
any registration of the device. Registration termination is notified
through the `registration-ends` event type, which requires its own
subscription.

The example uses `sinkCredential` for authenticated event delivery and
a `subscriptionExpireTime` to control the subscription lifetime. Check
callback examples to check some possible events received:

- New incoming call
- Registration revoked
a `subscriptionExpireTime` to control the subscription lifetime.
value:
protocol: HTTP
sink: https://notificationServer.opentelco.com
Expand All @@ -1640,11 +1640,11 @@
subscriptionExpireTime: "2024-11-17T13:18:23.682Z"
SESSION_SUBSCRIPTION:
description: |-
A sample of media `session-status` subscription for a specific
`mediaSessionId` at `acme.opentelco.com`.
A sample of media `session-status` subscription for a `deviceId` at
`acme.opentelco.com`.

Identified by for `mediaSessionId`, and validated via a `registrationId`
the endpoint is able to interact with its own media session.
This will be used to receive status updates of any media session of the
device, identified in each event by its `mediaSessionId`.
This could be used to remotely control the call or to handle the async
session establishment. For instance, updating the user interface for
different statuses: InProgress, Ringing, Cancel, etc.
Expand Down Expand Up @@ -1770,8 +1770,8 @@
When a re-registration is requested from server, maybe due to expire or
administrative token revocation or due any other technical reason. It
is expected from the endpoint to re-register. No new sessions will be
delivered to the user endpoint, as the subscription is not valid
anymore.
delivered to the user endpoint until it re-registers. Event
subscriptions are bound to the `deviceId` and remain active.

Here, an example of how the network will communicate to the client that
the registration is not valid anymore, detailing on
Expand Down
Loading
Loading