Proposal to establish API Families as Working Groups across API Sub Projects

[hdamker]

Introduction

Addressing the topic of “API Families” vs “APIs” seems to be prerequisite for a proper release management. It is also addresses observed concerns to onboard new API proposals as independent sub projects (due to the number of projects and its overhead and the risk of “API islands”).

The proposal below is derived from the presentation held within the TSC Meeting on Nov 2nd, 2023. It is related to camaraproject/ReleaseManagement#4 and the consolidation sssue for open points release management camaraproject/Governance#67 in Commonalities.

Problem description

CAMARA has currently a very heterogenous structure, one release management solution would not fit for all:

• Repository with a single API (e.g. QoD)
  • Repository release = API version
• Repository with multiple, closely related APIs (e.g. DeviceLocation)
  • Repository release might make sense to be used for the set of APIs if their lifecycle has anyway close dependencies and will follow same lifecycle phases, they will be always released together
• Repository with loosely coupled APIs (“API Family”) (e.g. EdgeCloud)
  • Repository release difficult to manage or even meaningless, APIs with different lifecycle stages
• Set of repositories with single APIs, which are managed by a joint group of people in one meeting (e.g. NumberVerify, SimSwap, OTP Validation)
  • Independent repositories (and versioning), but managed by a “working group”

Proposal

The proposal is to restrict the scope of a Sub Project to the development of one API or a few closely related APIs which have the same life cycle. Work across multiple APIs which should be maintained together due to their dependencies ("API Families" or categories of APIs) should be done within a Working Group.

An “API Family” working group

• can manage multiple sub projects with one mailing list, regular meeting, meeting minutes
• will be able to manage dependencies between related APIs
• responsible for the development of the API family
• participants will be at (mandatory) the maintainers of sub projects which are belonging to the "API Family" plus everyone else who is interested in the API Family and wants to contribute to it or one of its API sub projects
• working group material can be organized within the CAMARA Wiki (overview page, meeting minutes, ...) and does not need a Github repository
• criteria for an "API Family" could be that the same people managing the set of APIs anyway and/or the APIs are content wise related (e.g. ClickToDial and WebRTC)

Sub projects will manage only one or few very closely related APIs with same release cycles

• with dedicated code owners and maintainers, responsible for the artefacts within the repository
• allow independent decisions about releases per API or the set of APIs
• will be organized as a repository within the CAMARA Github organization

Benefits of this proposal

• Scalability: a new API sub projects will not necessarily mean a new mailing list, regular meeting and reporting overhead => CAMARA can onboard more API sub projects
• Flexibility: the shift of an API into or out of an API family will not impact the API repository content and can be done at any time if needed
• Visibility of APIs: the APIs of an API Family are visible as there own repositories. A large sub project like EdgeCloud can spin off agreed API sub projects into own repositories

Possible next steps

• [ ] Discussion of the proposal within the issue here
• [ ] Analyze need changes within the Project Charter and Project Structure and Roles documents to establish the working groups
• [ ] Create a proposal how to organize the existing APIs / sub projects into Working Groups and API Sub Projects

Note: not all API sub projects need immediately moved into a working group – well running projects shouldn’t be disturbed.

[hdamker]

How to group repositories within Github:

• @Kevsy proposed to look into Github Lists (note: seems to be a mechanism to organize starred repositories in personal profiles, but not in an organization like GitHub)
• There is no hierachy within Github beyond using organizations. The proposed way to organize repositories seem to be to classify repositories with topics

[hdamker]

Transfering to https://github.com/camaraproject/ReleaseManagement

[Bart-Ericsson]

I think I like the idea of “API family working groups” as it would enable the same group of people working on APIs in the same “domain” even if they are not closely related.

I also like the idea of sub project only including one or a few APIs that are closely related. Makes sense.

I read between the lines that an “API family working group” could handle several sub projects.

What it does not address (from what I can see) is challenge of the repository release number vs the version of the individual APIs in the repository. As an example:

Device Location. Repository release 0.2 will include

• Location Verification API 0.2
• Location Retrieval API 0.1
• Geofencing API 0.1

This has previously lead to confusion for those APIs that have not the same version as the repository version. This could very well happen in the future when APIs mature. Say that in the future it is only one of the APIs that would have changes in a repository release. Something like (hypothetical example) Location Verification API goes to 2.0 (non backward compatible change). The whole “repo” should make increase a major version as well? And then Location Retrieval API goes 2.0 – also a non backward compatible change. Now “repo” is not backward compatible with “repo 2.0” state, should it be 3.0 now?

Device Location (repository)	1.0	1.1	1.2	1.1	1.5	2.0?	3.0?
Location Verification API	1.0	1.0	1.1	1.1	1.1	2.0	2.0
Location Retrieval API	1.0	1.1	1.1	1.1	1.1	1.1	2.2
Geofencing API	1.0	1.0	1.0	1.1	1.1	1.1	1.1
New API	-	-	-	-	0.1	0.1	0.1

Another example As of now SimSwap group has 2 APIs inside:

1. GetDate and CheckSimSwap are described as a single API with two endpoints (this is questionable, but this is so).
2. event notifications - separate swagger file, not yet merged to the master.

These two APIs expected to be rather loosely coupled: right now for the whole group version 0.4.0 is released, and this release does not include event notification API at all. Following the suggested approach: these two APIs must be split into two subprojects/repos. This solves versioning issue.

What I’m not sure about is – there is no common umbrella like “SimSwap” for them anymore:

• there is no common name, common readme.md.
• Technically SimSwap and SimSwapNotification become as independent as SimSwap and DeviceLocation.

[Kevsy]

For the mismatch of release number and API :

As long as the release is sequential then it does not need to be a number. So it could be a date (like e.g. Gaia-X releases) or (like Android releases), names with ascending initial letter. E.g. The Android Lollipop release encapsulated multiple libraries all with different versions.

[tanjadegroot]

The release management process now decouples the release numbering from the API version numbering. It is also allowed to release closely related APIs together in one release under certain conditions if these APIs are not split out into individual repositories. The recommendation is to move this issue for the discussion on use of working groups for API families / groupings to the Governance project @hdamker

[hdamker]

Closing as discussed within TSC June 6th (Replaced by #142).