fix: rename endpoints to comply with Commonalities r4.3 (issue #235)

[rartych]

Here is the drafted PR description:

---

What type of PR is this?

• correction

What this PR does / why we need it:

Renames both POST endpoints to comply with the CAMARA API Design Guide (Commonalities r4.3, §6.5), which requires that when POST is used for transferring sensitive data rather than creating a resource, the path must use a verb.

Changes applied:

	Old	New
Path	POST /unconditional-call-forwardings	POST /check-unconditional-forwarding
operationId	retrieveUnconditionalCallForwarding	checkUnconditionalCallForwarding
Scope	call-forwarding-signal:unconditional-call-forwardings:read	call-forwarding-signal:unconditional-forwarding:check
Path	POST /call-forwardings	POST /retrieve-forwardings
operationId	retrieveCallForwarding	retrieveCallForwardings
Scope	call-forwarding-signal:call-forwardings:read	call-forwarding-signal:forwardings:retrieve

• Updated summary and description fields on the /check-unconditional-forwarding operation to use the verb "Check".
• Updated all prose references to the old endpoint names in info.description.
• Renamed both Gherkin test feature files to match the new operationIds and updated the Feature: title line and Given the path step accordingly.

Which issue(s) this PR fixes:

Fixes #235

Special notes for reviewers:

The verb choice for the unconditional endpoint is check (not retrieve) because it returns a simple boolean status, not a resource. The verb for the general forwarding endpoint remains retrieve since it returns structured data. Scope strings are updated to follow the new path verb: unconditional-forwarding:check and forwardings:retrieve.

No API semantics, schema names, or response shapes were changed.

Changelog input

release-note: Rename POST endpoints to comply with CAMARA API Design Guide Commonalities r4.3 (issue #235): /unconditional-call-forwardings → /check-unconditional-forwarding, /call-forwardings → /retrieve-forwardings

Additional documentation

[tanjadegroot]

I did like the original suggestion by Eric to postfix the endpoint name with "-status" so you know what is being checked.

So actually all operations could be focused on the forwarding-status. this would allow to drop "call" from most names to avoid duplication with the API name "call-forwarding-signal" (*).

If you keep as is, I think in the above table the call-forwarding-signal:unconditional-forwarding:check is missing the word "call" -> call-forwarding-signal:unconditional-call-forwarding:check ?

My above proposal could give:

	Old	New
Path	POST /unconditional-call-forwardings	POST /check-unconditional-forwarding-status
operationId	retrieveUnconditionalCallForwarding	checkUnconditionalForwardingStatus
Scope	call-forwarding-signal:unconditional-call-forwardings:read	call-forwarding:unconditional-forwarding-status:check
Path	POST /call-forwardings	POST /retrieve-forwarding-status
operationId	retrieveCallForwarding	retrieveForwardingStatus
Scope	call-forwarding-signal:call-forwardings:read	call-forwarding:forwarding-status:retrieve

Final point: one could in addition drop the word "forwarding" from all items, as it is in the API name already.

(*) Side note: I never quite liked the "signal" aspect in the API name as it does not sound like a resource, so the API name could just be "call-forwarding". I included that in the above table. For the resource "CallForwardingSignal", the term "ForwardingStatus", "ForwardingIndicator" or "ForwardingFlag" could be an alternative.

But that implies updating of file names and documentation as well.

Don't forget updating the test files, API description, etc. ...

[rartych]

@tanjadegroot Thanks for looking into proposal.
I wanted to shorten the names (path, operationId etc.), then adding "-status" looks awkward for me.
As POST /unconditional-call-forwardings returns boolean value @eric-murray suggested to differentiate it with "-status".
My current proposal differentiate 2 endpoints by the verb used:

• "check" - returns boolean status
• "retrive" - returns array.

I also tried to take into account Guidelines for MCP and AI Agent Readiness to have meaningful but short names.

There are other not urget issues raised in Release Review, so the API would be modified significantly after Sync26.

[eric-murray]

I'm happy with the proposal. I agree that using the check verb implies that some sort of status will be returned.

[bigludo7]

LGTM
Thanks Rafal

[tanjadegroot]

@tanjadegroot Thanks for looking into proposal. I wanted to shorten the names (path, operationId etc.), then adding "-status" looks awkward for me. As POST /unconditional-call-forwardings returns boolean value @eric-murray suggested to differentiate it with "-status". My current proposal differentiate 2 endpoints by the verb used:

• "check" - returns boolean status
• "retrive" - returns array.

I also tried to take into account Guidelines for MCP and AI Agent Readiness to have meaningful but short names.

There are other not urget issues raised in Release Review, so the API would be modified significantly after Sync26.

Hi @rartych, I understood, I still find the API a bit awkward with its resources that are very close. But anyway you can drop my comment or look at it later as you wish.
In your current proposal, then you kept the word "Call" in the 2 operationIds on purpose, even if not present in the new endpoints ?

[rartych]

In your current proposal, then you kept the word "Call" in the 2 operationIds on purpose, even if not present in the new endpoints ?

Yes, as operationId should be easy to transform into self-descriptive MCP tool names - API name as a prefix of MCP tool name is also possible, but we need to define respective rules in CAMARA MCP Tool Definition Guide first.
The simplest way of transformation is:
checkUnconditionalCallForwarding -> check_unconditional_call_forwarding