Missing guideline for file names of API definition files - mixed use of snake_case and kebab-case

[hdamker]

Problem description

There is currently no guidelines for file names of API definition files in CAMARA.

The release candidates for Fall24 are all using the API name together with .yaml, but a mix of snake_case and kebab-case. For consistency in the meta-release and to be prepared for future automation with scripts this must be harmonized.

The API Design Guideline has already a definition of api-name in chapter 11.6.1 Scope Naming:

api-name is the API name specified as the base path, prior to the API version, in the servers[*].url property. For example, from /location-verification/v0, it would be location-verification

Within the path the api name must be in kebab-case. The proposal is therefore to use the convention api-name.yaml as a guideline for the API definition file names.

Possible evolution

• Define within the next version of Commonalities a guideline for the API Definitions file names
• Ensure that all Commonality artefacts are using the same convention to make their use easier (e.g. CAMARA_common.yaml vs notification-as-cloud-event.yaml in the same directory)

The changes might shouldn't be done in Commonalities 0.4.0 to avoid broken links, but a decision for the format should be taken, so that API Sub Project voluntary can do the change already for the Fall24 release, e.g. as part of their release PR for M4.

Alternative solution

Additional context

The majority of APIs in the Fall24 meta-release are using already the convention api-name.yaml.

snake_case is currently used in five repositories, where SimSwap is mixing both variants:

• https://github.com/camaraproject/CallForwardingSignal/blob/r1.2/code/API_definitions/Call_Forwarding_Signal.yaml
• https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.1/code/API_definitions/carrier_billing.yaml
• https://github.com/camaraproject/CarrierBillingCheckOut/blob/r1.1/code/API_definitions/carrier_billing_refund.yaml
• https://github.com/camaraproject/HomeDevicesQoD/blob/r1.1/code/API_definitions/home_devices_qod.yaml
• https://github.com/camaraproject/NetworkAccessManagement/blob/main/code/API_definitions/network_access_management.yaml
• https://github.com/camaraproject/SimSwap/blob/r1.1/code/API_definitions/sim_swap.yaml ... but: https://github.com/camaraproject/SimSwap/blob/r1.1/code/API_definitions/sim-swap-subscriptions.yaml

[PedroDiez]

From TEF side we are agree with this issue and its resolution:

• To formally define it in the next version of commonalities
• Up to each WG to consider in advance for current MetaRelease in APIs

[bigludo7]

From Orange perspective agree as well on the issue & resolution.

[shilpa-padgaonkar]

@rartych Could you kindly create an issue in the subprojects identified by @hdamker above so that they can already change the file names. @bigludo7 has already created it for simswap.