Update BYON-Calling, BYON-RACM, BYON-Notification: resourceURL to sessionId/channelId

[deepakjaiswal1]

Update BYON-Calling & BYON-RACM service: Modify resourceURL identifier to vvoipSessionId/racmSessionId.

BYON-CallHandling-Serivce:

• changed resourceURL to vvoipSessionId
• API PATH updated

BYON-RACM-Service:

• changed resourceURL to racmSessionId
• API PATH updated

[deepakjaiswal1]

New changes:
BYON-Notification-Channel:

• resourceURL to channelId
• Change POST /channels from creating a list of channels to a single channel
• Change GET /channels to GET /channels/{channelId}
• Added OUT /channels/{channelId}
• Added DELETE /channels/{channelId}

BYON-RACM-Service:

• Simplified the channelId

[pradeepachar-mavenir]

Non-inclusion of Resource-URL in all APIs (common to all the three APIs):

• In REST-based API design, having a resource URL to identify the REST object is a fundamental principle and considered a best practice. A resource URL plays a crucial role in RESTful APIs as it uniquely identifies resources and allows clients to interact with them using standard HTTP methods without having to rebuild the URL. By following RESTful principles, each resource should have its own URL, which serves as a unique identifier for that resource. Therefore, in REST API design, having resource URLs to identify REST objects is not only recommended but essential for creating well-structured and easily navigable APIs.

• The objective of CAMARA is to provide simple, easy-to-use API that require low coding effort. Expecting client to follow certain instructions and rebuild the URL is adding an unnecessary step in it’s interaction with the operator’s network.  

• Our strong preference and recommendation are for the client to reuse the resource-url as-is provided by the server. The resource-url will be the base url and clients can append sub paths, like '/status' etc. for subsequent operations on the session.

• Having clients building the URL creates a dependency on the client, which will lead to challenges with maintainability of the API. In the subsequent release, if there is a need for server to enhance the URL for any reason, then the client implementation will need modification, lot more challenging task compared to a network change.

• Also, the usage of server returned uri is inline with the 3GPP 29.501 Principles and Guidelines for service definition.

[deepakjaiswal1]

@pradeepachar-mavenir @TEF-RicardoSerr

Challenges with Direct Resource URLs:
• Security: Exposing backend systems through API Gateways enhances security, but it also creates a disconnect. Backend systems remain unaware of changing exposure points managed by the gateways. This makes it difficult to generate resource URLs directly usable by developers' applications.

Benefits of Constructing Resource URLs:
• Simplicity: Constructing resource URLs from a base URL, API paths, and resource IDs is a straightforward approach, especially when well-documented using tools like Swagger. This allows developers to easily understand how to build URLs based on the API documentation, making the development process intuitive.

Drawbacks of Rigid Resource URLs:
• Limited Flexibility: Requiring clients to strictly adhere to server-provided resource URLs can hinder the API's flexibility and agility. Server-side URL changes (modifications or enhancements) for future releases could break existing client implementations, leading to additional maintenance burdens.

Proposed Solution: Dynamic Configuration with Base URLs:
• Clean Server Migrations: We propose that developer applications support dynamic configuration parameters (e.g., Firebase Remote Config). This allows apps to fetch the base URL and reconstruct resource URLs on the fly (Base URL + API Path + Resource ID). This strategy facilitates clean server migrations without requiring client upgrades.

Separation of Concerns: Routing vs. Resources:
• API Clarity: Embedding routing information directly within the API path can introduce complexity and potential issues. Separating the resource URL from routing details keeps the API design clean and focused. Past experiences show that overloading API paths with routing information leads to complications. Avoiding this practice ensures long-term flexibility and maintainability of the API.

Balancing Standards with User Needs:
• User-Centric Design: While adhering to 3GPP principles is important in specific contexts, prioritizing the specific needs and requirements of the API's user base is essential. 3GPP guidelines may not always perfectly align with CAMARA's goals of simplicity and ease of use.

Consistency within CAMARA Projects:
• Interoperability and Developer Experience: Consistency in API design across CAMARA sub-projects is crucial for interoperability and developer experience. Spot-checks reveal that most CAMARA sub-projects already predominantly use resource IDs over resource URLs. This consistency not only simplifies development but also reinforces the idea that resource IDs align well with CAMARA's overall design philosophy.

[TEF-RicardoSerr]

I have been cross-checking with other project maintainers within Camara. In general terms what I have been told is that it is more desirable to led the creation of the URL to the developer rather than the API endpoint and that it is better to return a sort of ID so an SDK later build the URL. A couple of examples:

• EdgeCloud
• QualityOnDemand

In these examples they are just providin the parameters and the needed information to build an URL rather than the URL directly

[pradeepachar-mavenir]

Notification channels created will be associated with the device instance from which the WebRTC sessions are being initiated. Removal of {deviceId} from the URI will lead to WebRTC gateway not associating channels to the deviceId. Please share your rationale for removal of deviceId, as stated our preference and recommendation is to retain it so that the network can maintain the device instance to notification channel association.

[deepakjaiswal1]

@pradeepachar-mavenir @pradeepachar-mavenir

We understand your preference to retain the deviceId in the URI for associating notification channels with WebRTC sessions. However, we propose removing it as a mandatory parameter for the following reasons:

ClientId Sufficiency for Gateway Channels: When using a WebRTC gateway that supports notification channels, the clientId can uniquely identify the device instance initiating the session. This eliminates the need for an additional deviceId parameter.

External Service Flexibility: For notification channels managed by external services, the notification channelId provided during WebRTC session creation already establishes the association. Introducing deviceId adds unnecessary complexity.

Multi-Device Notifications: Certain use cases, such as a calling service, might require a single notification channel to receive notifications for multiple devices. Removing the mandatory deviceId allows developers to implement this scenario by using a common Webhook notification channel. This channel would then deliver notifications to a central web service, which would then handle routing them to the specific devices.

Therefore, we recommend making deviceId an optional parameter to provide flexibility and cater to diverse notification channel implementations.

[TEF-RicardoSerr]

As there was a previous merge I fixed the conflicts there were with this one, please @deepakjaiswal1 @pradeepachar-mavenir

review again