search

camaraproject / WorkingGroups

Repository for the CAMARA Working Groups
41 stars 60 forks source link

Challenging use of snake_case regarding current situation #157

Closed bigludo7 closed 1 year ago

bigludo7 commented 1 year ago

I'm sorry to call into question a validated point about use of snake_case instead of camelCase but I'm bit uncomfortable about this direction regarding the facts that:

I see what we could lose to not use camelCase (misalignment with other SDO and so complicated the telco software developer coding our api on their product) but I did not see the added value of the snake_case.

As we have not aligned our APIs it is perhaps no to late to challenge our decision?

Looking for feedback from this community.

hdamker commented 1 year ago

I'm supportive here as I find the argument about being in line with TMF, 3GPP, Google (and in consequence also Kubernetes / CNCF) compelling. In addition I'm not aware of any strong rational for the use of snake_case.

@jordonezlucena @jlurien: as the original proposal within the guideline came from your direction, any thoughts on it?

hdamker commented 1 year ago

As a side note, here the view of ChatGPT on it:

Should I use CamelCase or snake_case in OpenAPI specs?

In OpenAPI specifications, you can use either CamelCase or snake_case for naming properties, parameters, and other elements. The important thing is to be consistent in your use of case throughout the specification.

However, CamelCase is more commonly used in OpenAPI specifications because it is the naming convention recommended by the specification itself. According to the OpenAPI Specification, the property names and other identifiers should use "lowerCamelCase" convention.

patrice-conil commented 1 year ago

CamelCase is very popular in naming convention of most popular languages like Java, Javascript, C#, Kotlin, Go, Swift ... so I agree with Ludo proposal.

RubenBG7 commented 1 year ago

Related to: "A lot of of our current API are still using camelCase (QoD, Sim Swap Mobile connect flavor, Edge cloud, Carrier billing, etc..)"

These APIs was working in parallel to CAMARA API Design Guidelines, that's why some contains a bad naming convention according to the Guidelines approved in CAMARA Commonalities.

Now we are working in TMF Catalyst where first OAM APIs proposal have been designed and presented according to the actual guidelines (With snake_case naming convention). Peope in TMF Catalyst understand that take one naming convention or other is only an appearance thing and it does not impact in the functionality. These APIs are now on develop process, will be presented in the DWT Asia and after that will be included on CAMARA.

Don't really understand why after guidelines approval and revision by all people involver in CAMARA, now we are going to reopen an appearance question that does not impact in functionality.

If we would change this appearance thing, will impact in all actual API Designs onboardings and time plans.

bigludo7 commented 1 year ago

Thanks Ruben

I'm also part of the TMF/Camara catalyst and I respectfully disagree on your assessment. In this catalyst, decision to use OAM API to follow snake_case is not validated and trigger discussion. There is a good rational to not move to snake_case there: it will break TMF conformance.

We face this conformance issue there and probably as mentioned by @hdamker in our work with other SDOs. If we're not able to use TMF or 3GPP API directly don't you think it will reduce our functional capability ?

As of today none of our APIs in in v1.0 correct ?
I'm not sure moving to camelCase will be a great effort as lot of our API are not follow snake_case. For the APIs where I'm code owner I can reassure you that it can be done quickly without huge impact as the API have few attributes.

I understood your reluctance from a project delivery but not get in your answer good rationale to keep snake_case for value-added at the end of the day. So I respectfully reiterate my request to open again this point.

bigludo7 commented 1 year ago

I make a quick survey on our current assets to have 'some meat' behind the request:

numberVerification: snake_case - but only 2 attributes subject to case OPT : snake_case - 2 attributes QoD: camelCase MEC Exposure & Experience - camelCase MEC Edge Cloud: camelCase and note that we have hundred of attributes in this API TrafficInffluence: camelCase Anonymised Identifier: no attribute subject to case Device Identifier: no attribute subject to case Home Device Qod : snake_case but only one attribute subject to case deviceStatus: camelCase simSwap : we have 2 versions - one is camelCase and the other snake_case Carrier Billing: we have 2 versions - one is camelCase and the other snake_case

So as of today, as a team, we have more work to stand to snake_case than shifting to camelCase. A point to consider.

hdamker commented 1 year ago

@bigludo7 Thanks for all the effort with the survey and as said I agree with your proposal. But what is the purpose to assign multiple people to this issue? We need one who is writing the short PR if it is agreed within the Commonality team to do this change.

bigludo7 commented 1 year ago

@bigludo7 Thanks for all the effort with the survey and as said I agree with your proposal. But what is the purpose to assign multiple people to this issue? We need one who is writing the short PR if it is agreed within the Commonality team to do this change.

Oh sorry for the spaming ! We are in the commonalities meeting and @jordonezlucena told me that I have to add assignee from the companies involved... or I misunderstood perhaps his point.

hdamker commented 1 year ago

I

We are in the commonalities meeting and @jordonezlucena told me that I have to add assignee from the companies involved

If this is the intention then @rartych is sufficient for DT.

jordonezlucena commented 1 year ago

Thanks Ruben

I'm also part of the TMF/Camara catalyst and I respectfully disagree on your assessment. In this catalyst, decision to use OAM API to follow snake_case is not validated and trigger discussion. There is a good rational to not move to snake_case there: it will break TMF conformance.

We face this conformance issue there and probably as mentioned by @hdamker in our work with other SDOs. If we're not able to use TMF or 3GPP API directly don't you think it will reduce our functional capability ?

As of today none of our APIs in in v1.0 correct ? I'm not sure moving to camelCase will be a great effort as lot of our API are not follow snake_case. For the APIs where I'm code owner I can reassure you that it can be done quickly without huge impact as the API have few attributes.

I understood your reluctance from a project delivery but not get in your answer good rationale to keep snake_case for value-added at the end of the day. So I respectfully reiterate my request to open again this point.

As I said, we might need go to a voting decision -- let's double check with @MarkusKuemmerle the steps we need to take. However, I think it's fair to demand having a rationale with technical grounds as part of this polling. We don't think going for snake_case causes loss of functionality -- it's a matter of choice, purely cosmetic. Having noted this, let me highlight the importance of including this rationale built upon technical grounds -- we need to make everybody aware why this voting decision is taking place. And we strongly believe that if the group decides to vote to change something that was agreed two months ago, we need to demonstrate that the original decision was either wrong or worse than the new one.

bigludo7 commented 1 year ago

Thanks @jordonezlucena and looking for @MarkusKuemmerle guidance. As I tried to explain, the point is not technical : Perhaps you'll be disappointed but I will not find a code generator breaking for any of this case

My point was about:

  1. Where are we currently ?--> survey
  2. As we are not the only organisation in the telco industry, how our choices fit in the industry ? and how we can reuse existing industry asset ? --> point about 3GPP, OMA, TMF, MEF, edge cloud API
  3. What are the current situation with the web giants ?--> point about google map apis & amazon api

If we took it only from the technical side, I'm afraid that we'll miss the boat.

Anyway, thanks for the discussion and happy to provide my perspective

patrice-conil commented 1 year ago

@jordonezlucena As an API developer, I'll try to give a technical point of view. What appears to be cosmetic can be a lot of work in name translation. It's not the most glamorous job of a developer and I hate doing it because it doesn't add any value. As we are working with 3GPP APIs on the SCEF/NEF side...all target field names are "camelCase". If CAMARA is there to facilitate the adoption of APIs by third-party developers, why complicate the work of the developers of the APIs themselves?

Sorry for not having seen that in the rereading of the guidelines but we were in the process of specifying APIs in camelCase... I thought it was acquired. My appologizes.

shilpa-padgaonkar commented 1 year ago

Support the proposal to use camel case

hdamker commented 1 year ago

These APIs was working in parallel to CAMARA API Design Guidelines, that's why some contains a bad naming convention according to the Guidelines approved in CAMARA Commonalities.

There is neither "bad" nor "good" naming conventions here, it is just about consistency. And as multiple times mentioned, not only within CAMARA but also with other relevant project which are very close to us, like 3GPP and TMF.

The recommendation/examples in OpenAPI spec in camelCase might be another argument, as following these would allow people just learning about OpenAPI spec to have an easier start within the project.

We are currently at the point where the effort to adapt the one or other naming convention is a) a considerable low effort due to nascent phase of the project and b) higher for snake_case then for camelCase (as the survey showed).

Therefore my support for the proposal to use camelCase and change the guideline in this point.

sharrop commented 1 year ago

Hi,

_Now we are working in TMF Catalyst where first OAM APIs proposal have been designed and presented according to the actual guidelines (With snakecase naming convention). People in TMF Catalyst understand that take one naming convention or other is only an appearance thing and it does not impact in the functionality. These APIs are now on develop process, will be presented in the DWT Asia and after that will be included on CAMARA.

Like @bigludo7, I am also on this TMForum catalyst, and - as the TMForum's API lead - I also fundamentally disagree with this summary. We have just spent another 2-hour call today stuck on the snake_case vs lowerCamelCase discussion, in full knowledge that:

Excerpt from 3GPP TS 29.501 V18.0.0 (2022-12): Principles and Guidelines for Services Definition:

image

jordonezlucena commented 1 year ago

@sharrop: regarding 'defacto CAMARA API convention', there are agreed API guidelines in this forum. The examples you posted here, here, here and here are v0.x (and not v1.0) -- precisely because v1.0 means alignment with guidelines.

@patrice-conil @hdamker:

If there is a challenge to modify the agreed guidelines, there should be a strong argument behind which justifies why the new proposal is significantly better than the current one.

hdamker commented 1 year ago

@jordonezlucena: I won't continue to argue pro or con the cases ... there are for sure arguments for both. Finally I could live with both, not worth a religous debate.

But I don't agree fully with the following:

The examples you posted here, here, here and here are v0.x (and not v1.0) -- precisely because v1.0 means alignment with guidelines

At least three of these APIs are already implemented by operators (including yours) and the alignment with the guidelines is not the sole criteria for declaring them v1.0. There are also good reasons to test them thoroughly by implementations and with developers before we are confident enough that they don't need further breaking changes and we can commit to maintain them over longer time. But you are right that we are in pre v1.0 status and still able to do breaking changes (e.g. chosing more developer friendly parameter names) and therefore are also able to change the notation.

sharrop commented 1 year ago

@jordonezlucena:

there are agreed API guidelines in this forum

Could you provide a link to the reviewed/agreed/published version of these design guidelines? I can only see the current version in the main dev branch. If the main dev branch is what you are referring to as the "agreed" version, then it looks like this changes weekly presumably by lazy consensus against each pull request?

I am simply proposing a further change, as are Orange, DT and other members on this thread. Perhaps instead of raising this issue for debate in a thread, the correct way to do this is simply to edit the document directly and wait for it to appear on the main branch?

Alignment with other Telco projects (TMForum, 3GPP) does not avoid having to rename properties, as in CAMARA we have decided to choose dev-friendly, not Telco-specific terms.

A few points:

"Developer-Friendly" and "Telco-Specific"

  1. There is nothing Telco-specific in the TMForum API Design Guidelines. Just like Amazon's, Google's etc, these API guidelines are simply a collection of REST API best practices that state a position on naming, filtering, pagination, queries, tasks, patching, asynchronous events and more. They are no more telco-specific as they are insurance, healthcare, agriculture, finance or deep-space exploration -specific.
  2. If you are referring to the terminology used within the payload, then the CAMARA API Design Guidelines are currently explicitly encouraging this (2.1 Domain Driven Design):

    The main idea of the Domain Driven Design (DDD) approach is "to develop software for a complex domain, we need to build a ubiquitous language that embeds the domain's terminology in the software systems we build" (Fowler, 2020) ... As an initial reference to define the different domains and subdomains, we rely on the TM Forum SID model

  3. When you say "dev-friendly" - can you be specific and objective - so that we can all come away with the same interpretation? For example, if you can say that your developers insist on camel_case, I can say that my developers insist on lowerCamel. This "developer friendly" language gets us no-where unless you can present data to justify it.

  4. in CAMARA we have decided to choose dev-friendly, not Telco-specific terms

    I applaud the objective, and I see that further detail is provided in the CAMARA API Design Guideline (2.5 Reduce telco-specific terminology in API definitions):

    Avoid terms/types specific to a given telco domain. For example the acronym 'UE': in 3GPP terminology this refers to 'User Equipment', but 'UE' means 'User Experience' for most Web developers: 'Terminal' would be a more appropriate, and unambiguous, term.

    What are we therefore going to do about the fact that virtually every CAMARA API references a ueId (description: User equipment identifier), that contains an MSISDN, ipv4addr and ipv6addr; and that all other CAMARA APIs are littered with very telco-specific terms (qosStatus, UE_ROAMING_STATUS, ROAMING_OFF, HOME_DEVICES_QOD.RSSI_BELOW_THRESHOLD). From the above guideline, these are explicitly banned.

By way of comparison, you won't find an MSISDN attribute or any of these terms in any TMForum API - because that is too ...telco-specific, and TMForum APIs are being applied in other domains beyond telco, so please can we have a more honest debate without relying on old-tropes.

hdamker commented 1 year ago

@sharrop Thanks for your comments, appreciated that you are supporting with your experiences out of the TMF work.

I agree with you regarding the status of the design guidelines. They were reviewed before merged into main based on an agreement within the commonalities working group. But there is no release process for them yet, and the number of issues which are discussing changes shows that we have a good starting point, but not yet a version which is perfect or even consistent. Some examples are #118, #124, #142, #151, #156 which are all open. And that's ok ... we are here not in a standardization organisation where each and every achieved sentence is written in stone, but in a community where people want to create APIs which are working for developers.

Your discussion "developer friendly" and "telco specific" might be off-topic within the concrete issue, but just one remark:

4. What are we therefore going to do about the fact that virtually every CAMARA API references a ueId (description: User equipment identifier), that contains an MSISDN, ipv4addr and ipv6addr; and that all other CAMARA APIs are littered with very telco-specific terms

This is work in progress as we are fully aware of it. See https://github.com/camaraproject/WorkingGroups/pull/120 and the related issues in each and every sub project, for example in QualityOnDemand https://github.com/camaraproject/QualityOnDemand/issues/90 and https://github.com/camaraproject/QualityOnDemand/issues/97.

For terms like UE and MSISDN it is obvious that they need to be replaced to achieve our objective, for some others like "IP v4 address" (see that I'm avoiding to use either case :-)) it is unavoidable to use them as we are dealing here with networks. Being completely abstract would also not help as we don't want to create a complete new "CAMARA language" which would require developers to first learn a lot of new definitions before they can understand the APIs. We need to meet developers where they are coming from (the web and cloud world) and use as many of the terms they are used to.

sharrop commented 1 year ago

Thanks @hdamker for your balanced view, and @jordonezlucena I understand your need for a technical justification. Let me explain the wider context, and so why this seemingly cosmetic detail has become a primary focus right now. I know @bigludo7 will be aware of this from his TMForum API team experience - which is why he raised the subject.

I fully support the initiative for standardised APIs to network capabilities, and that this has been the main focus of CAMARA to-date. I was in networks architecture during the Parlay/X and GSMA/OMA-OneAPI initiatives -- and I would like this one to succeed.

Now that CAMARA is getting into (in CAMARA terminology) "Service APIs" that overlap in business scope with incumbent TMForum capabilities - then it makes sense to leverage the work and experience of this space to achieve the aim. I recognise a lot of "early years" TMF experience in the current CAMARA work (hand-written swagger/OAS files with "best efforts" shared schemas, hand-written diagrams/documentation etc), so I feel your pain and I know that TMForum can greatly help here.

I empathise with the accusation that TMForum APIs can be seen as too-complex and too-generic - and we in Vodafone have made our own accommodations for this, both rarely applied, but useful:

  1. We have a concept of "Journey" or "Composite" APIs (comparable to Mulesoft's "Experience APIs" or Gartner's "Systems of Innovation") - these can simplify and short-cut multiple TMF-API calls.
  2. We have experimented with applying a GraphQL layer for "last-mile, over-the-air" API interactions - such as building the dashboard for a MyVodafone mobile app - where a single GraphQL query can succinctly return combined information and nothing else ("Hi Steve, Here's your bill"). This is just the reason why Facebook/Meta invented it, when they moved into mobile.

Both of these make TMForum APIs more simplified and "developer-friendly", but we maintain the principle that these are derived from the TMForum schemas that provide the foundational language and taxonomy: GraphQL schema can be derived from JSON-Schema, and Journey APIs can be described (in TMForum terms) as a combination of "Domain Context Specialisation" and "Component Suite". These and GraphQL have an ongoing active interest within the TMForum API community - which have a very heavy membership overlap with CAMARA.

This Schema-derivation is important - as it allows TMForum to evolve, and any derivation to follow it. For example, TMForum is soon to release ASyncAPI representations for all events - and I imagine this will be of keen interest to future CAMARA interactions. Some event-driven systems will interact only over events and not REST APIs - but the semantics and language need to be the same (eg: the status update of a product order) for the ecosystem to make sense of it.

In TMForum all Swagger/OAS files, Class diagrams, ASyncAPI files, Conformance Test Kits and Reference Implementations are machine-generated from higher-level meta-data. Before any v5 TMF API is fully-released, Java code generated from the OAS file will be hosted and run (with a MongoDB backend), a Postman script to exercise the interface will be auto-generated from the OAS file. That Postman script will be run against the reference implementation, and the class diagrams and user-guide will also be auto-generated into PDF and HTML. We have a "deep-diff" tool that can compare two versions of a Swagger/OAS file and produce a CHANGELOG which itemizes breaking, non-breaking and informational changes between versions. This gives us bulletproof quality and consistency, and allows us to scale with confidence.

All of this is on-offer to the CAMARA project from the TMForum.

To be proactive in this, the TMForum launched a catalyst project (a kind of public PoC) to demonstrate how CAMARA-OAM APIs can be derived from relevant TMForum schemas. If a CAMARA product order does not care about any prior Quote, Agreement, Account, Channel, Notes, Appointments, Terms or Related Parties -- then these have all been removed. It further combines the concept of order and payment (with similar simplification applied) into a single interaction.

On the TMF side, this can all be done by configuration of the meta-data (essentially saying "its a ProductOrder without X, Y and Z, and adding A, B and C") - allowing the CAMARA API to also have generated OAS, Class diagram, user-guide and postman scripts as an atomic release package. The aspiration is that the end result will be "a CAMARA API", on the CAMARA GitHub with a CAMARA name and number. We can use a CAMARA document template to brand the CAMARA user-guide in PDF, HTML and many other formats (derived from AsciiDoc).

This mirrors the TMForum's previous liaison with MEF, as the vast majority of the above was done as a result of years of collaboration with the MEF. All current MEF APIs (Sonata, Legato etc) are named, branded and hosted by MEF, but derived from equivalent TMForum APIs. They have fundamental differences (eg: MEF do not have the concept of a Product Catalog or a Party model, since they only need Buyer's and Seller's) - but they have an intrinsic degree of interoperability and familiarity.

So - back to the original point: The TMForum can do all of this for CAMARA by configuring and combining TMForum schemas (additions, removals and combinations) - and then generating all API artefacts from that. This will allow CAMARA to benefit from the TMF API "factory" outputs now and in the future.

However, TMForum schemas are written with lowerCamel, so if CAMARA - at such a relatively early stage in its existence - insists on snake_case over lowerCamel, then these APIs cannot be "derived from" the TMForum schemas. They will have to be bespoke, hand-written, and "on their own" in terms of future evolution alongside the TMF.

By "TMF" in this I mean all of the same mix of operators, integrators and vendors as are present in CAMARA. The TMForum API community are heading into OAS v3.1, ASyncAPI, GraphQL and more - and we would love to bring CAMARA work along in this journey as well.

shilpa-padgaonkar commented 1 year ago

Let's address this point shortly in our upcoming commonalities call next week.

patrice-conil commented 1 year ago

@jordonezlucena and @RubenBG7, You asked for technical arguments...many of them were given by @bigludo7 @sharrop or myself. Could you explain from a technical perspective what we would gain if we stayed on lower_snake_case?

Thank's in advance.

RubenBG7 commented 1 year ago

From my prospective, we're not gaining anything with one or with the other.

Cosmetic things does not impact in functionality.

That means there are not technical arguments to give here.

Here we need to vote AGAIN what is your selected cosmetic appearance for our CAMARA requests and response bodies.

sharrop commented 1 year ago

@RubenBG7 :

Cosmetic things does not impact in functionality. That means there are not technical arguments to give here. Here we need to vote AGAIN what is your selected cosmetic appearance for our CAMARA requests and response bodies.

As mentioned earlier in this thread, this is not a cosmetic issue. I hope you can see that:

If you are rejecting the premise/value of deriving CAMARA-OAM APIs from TMForum schemas, and so prefer to argue this as being just a cosmetic issue, then it would be better to state this so that we can focus on resolving the right issue in the right forum.

If there is a technical counter-argument, or a transparent motivation, then I genuinely want to engage with it as we need to balance the pros and cons in an objective decision.

shilpa-padgaonkar commented 1 year ago

Majority decides on camel case. TEF has pointed out its concerns regarding the impact on existing APIs in camara which currently follow snake case and would have to make the needed changes.

jordonezlucena commented 1 year ago

To complement the above statement, let me reinforce TEF position on this topic as I noted yesterday:

bigludo7 commented 1 year ago

@shilpa-padgaonkar @jordonezlucena May I proceed with a PR to change the guidelines ?

From my perspective you have highlighted these points yesterday but majority of the team attendees were in favor for the change. Looking for your guidance; Thanks

jordonezlucena commented 1 year ago

@bigludo7: to be totally transparent, before going for the actual PR, we prefer to open a formal voting (as used in other issues) and see position of every participant company. I think it's a fair request.

shilpa-padgaonkar commented 1 year ago

I am fine with taking a vote. @jordonezlucena : Would you like to set this up on the discussion board?

jordonezlucena commented 1 year ago

Dear all, I've set up a poll to capture votes in #169. Instructions and deadline are provided in the same poll.

shilpa-padgaonkar commented 1 year ago

Issue can be closed. Vote concluded with decision to use camelCase