How should multiple implementation contributions from providers of an API spec be managed in a Camara subproject?

[shilpa-padgaonkar]

No description provided.

[shilpa-padgaonkar]

@patrice-conil (Orange) has expressed interest to contribute a reference implementation for the QoD API

[MarkusKuemmerle]

In this case we could create 2 or more subdirectories below code/API_code for the different reference implementations. The API definition and API documentation should be the same, so there we shouldn’t need a differentiation

[MarkusKuemmerle]

@patrice-conil: Would you confirm the solution?

[patrice-conil]

@MarkusKuemmerle Solution is ok for me

[jordonezlucena]

@MarkusKuemmerle @patrice-conil @shilpa-padgaonkar : this solution is also fine by me

[Kevsy]

Fine by me

[patrice-conil]

@MarkusKuemmerle @jordonezlucena @shilpa-padgaonkar
I have a quarkus/kotlin implementation to share with you ... Have you any path / hierarchy to suggest ?
Maybe a split by technology like quarkus / spring ?

[MarkusKuemmerle]

@patrice-conil : For which API familiy / Sub Project do you have this implementation?

[patrice-conil]

@MarkusKuemmerle For QoD API (version 0.8.0)

[shilpa-padgaonkar]

Personally, I do not subscribe to the idea of having multiple ref. implementations (intended to be actively maintained) within a single repo

[patrice-conil]

@MarkusKuemmerle , @shilpa-padgaonkar
No problem, I'll keep mine for orange usage only.

[shilpa-padgaonkar]

@patrice-conil : Not at all, you should definitely contribute it to Camara. We would be very much interested in taking a look at your contribution and learning from it. My point was more about, how do we manage multiple ref. implementations in Camara subprojects in a clean way and can it be done within a single repo.

[jordonezlucena]

What about taking Markus' original suggestion: "In this case we could create 2 or more subdirectories below code/API_code for the different reference implementations. The API definition and API documentation should be the same, so there we shouldn’t need a differentiation" ?

[shilpa-padgaonkar]

@jordonezlucena @patrice-conil @SylMOREL : Let us discuss this topic in Wednesday call (19th Oct) and agree on how to proceed.

[shilpa-padgaonkar]

My 2-cents to our discussion on Wednesday :

1. Different contributors (organizations) are going to work asynchronously on their implementations (products), following their internal best practices/rules. They will want to contribute some particular version/release to Camara.
2. The release/version of a particular implementation (product) is a property that is maintained at the repository level by git. (e.g. git tag). Each contributed reference implementation will have its own release/version.
3. The contributor organization might not only contribute to Camara, but also might want to gain from the features contributed by external collaborators to the implementation by syncing the commits back to their internal repos.
4. The contributor organizations might want to automate the contribution process to Camara as much as possible, which is also done at repo level.

The above challenges are naturally supported by git when using one repo per implementation (product).
This would also mean that the main subproject repo would only include API specs and a list (with a link) for all available implementations under Camara organization.

The above points are written with the assumption that the contributions made to Camara will not be just a one-off activity, but rather an ongoing process with continuous effort to actively maintain the implementation/s in Camara.

[lbertz02]

Content of this comment are in new issue that can be found here - https://github.com/camaraproject/WorkingGroups/issues/99

[shilpa-padgaonkar]

@lbertz02 : All valid points mentioned above. Thanks for the same.
I would recommend you to kindly create a new issue with this broader scope. It would be very helpful if we could limit the current issue scope to managing multiple server implementations of an API in Camara in a clean way. There are 2 reasons for making this request:

1. DT would like to provide an update to its current QoD server implementation in Camara
2. Orange would also like to make its contribution for QoD server implementation in Camara ASAP
   The decision on this issue blocks both these activities.

[lbertz02]

CAMARA’s focus is API adoption. Successful adoption implies multiple, platform-specific implementations of the APIs and continual promotion of more implementations. Users will need to figure out which implementation best applies to them.

Projects that have wide adoption with complex implementations under a common repo are notorious for being large. Maintenance is challenging.

Separating the API repos from their implementations, i.e., seems the best option at this time.

1. Providing, in the API repo, references to implementations will give users the ability to choose the best option for them. Putting code in the API repo will tag it with the programming language and possibly turn off some.
2. We have not Validation Specification Documents for the API. Even though our APIs follow the openapi specification, one cannot claim that any implementation can be validated at this time.
3. We pin repos now so having many and pinning a few that lead to the APIs then they implementations is practical and consistent for projects with many repositories.

I propose existing implementation code be moved out of the current repo and into to a new one. Subsequent contributions should be in separate repos. A file linking those implementations should be placed in the current repo.

If one wishes to create a Reference Implementation, a new issue should be opened to discuss it and the supporting Validation Specification document.

[bigludo7]

My 2 cents in this discussion.

• what we are referring here as a reference implementation is the Camara api + code to 'interface' the API with a back end. I guess we can have several of them depending on Camara API version, back end supplier and version. This is very useful for any company targeting to implement the API.
• But perhaps we need also another 'kind' of implementation, a 'mock-up' implementation that will expose only the API without back-end (an API server + DB). The objective of this is slightly different: it could be use by developers planning to use the Camara API to discover it and we can use it probably for API validation (As mentioned by @lbertz02 previously this is also for me an important point for adoption) . This mock-up is only depend on Camara API versioning. We could associate to this some kind of postman collection to illustrate API use.

I guess we need to be very explicit about these 2 kind of implementation as they not target same objective and same audience.

[patrice-conil]

An API can be viewed from two sides, the provider and the consumer. Each of them needs a reference implementation from the other party to validate itself. For the provider, it's probably a collection of requests and expected responses (a postman collection for example). For the consumer, it is an implementation of a stub provider that returns expected responses corresponding to input requests. So we need probably only one reference implementation of a provider but as many as possible sample of consumers in different technos to encourage adoption.

[jordonezlucena]

Here's feedback from Telefónica on some of the topics discussed in the thread.

• We agree with the WoW proposed by @shilpa-padgaonkar and @lbertz02 as for separating API repos from their implementations.
• @lbertz02: with regards to Validation Specification Documents for the API, the idea is to use the API design guidelines drafted in PR Update API-design-guidelines.md #96, once approved.
• @bigludo7: in relation to the 'mock-up' implementation you propose in the second bullet, we think this can be covered with the 'try it out' option in the Swagger editor, as long as we specify a complete Swagger with well-defined examples.

[Kevsy]

+1 from Vodafone to assement from @jordonezlucena above

[patrice-conil]

Swagger's "try it out" option doesn't provide a mock of the provider part... you can't validate your consumer implementation with it.
I think what @bigludo7 called mock implementation is what I called "stub provider"...an implementation that returns predefined responses to consumer requests without requesting core services.

[bigludo7]

Thanks @patrice-conil - yes correct.

Surely too simplistic but I assume we have something like this :

To make sure we're on same page:

• A reference implementation is contributed code to implement (C). It is specific to a Camara API version and Back End. We could have several depending on back end flavor.
• A validation Specification document is use to validate (B) conformance. Is it also documentation for developer to built (A) or do we want to have distinct documentation?
• A Camara mock-up could provided to allow application developer to test their Camara API in standalone in order to emulate (C). It could be available on Camara git.

[shilpa-padgaonkar]

As agreed in commonalities, we will move the current QoD implementation outside the repo and every following contribution will get a repo of its own.

[patrice-conil]

Hi @shilpa-padgaonkar,
Ok for "the repo of its own" but where ? inside the camara project or in other project/repo or a fork ?

[shilpa-padgaonkar]

@patrice-conil : This will be inside Camara project.