Page Comparison

...

Multiple APIs in one API Sub-project

Issue: 

if multiple API endpoints are managed in one API sub project but in separate OAS definition files, each endpoint can evolve separately, but the release packages will mix-up the release of evolutions of these API endpoints.

Proposal:

Put each API endpoint in its own API sub-project such that individual release packages can be created for each API endpoint.

• Request API projects that contain multiple APIs to create separate sub-projects
• Add a confluence page linking the APIs of the same "family" to the CAMARA wiki.

Details:

GitHub release packages include the full API Sub-project.

If multiple API files are managed in one API Sub-project, then release package will include all APIs.

Proposal:

1) The notion of API family will not be release managed

...

. CAMARA release management

...

only

...

considers 

...

APIs.

...

2) The proposal is

...

to

...

• develop only one

...

If multiple API are managed in one API Sub-project, each API file shall have its own folder, such that release packages can be created with a focus on a specific API. The API name and the API version of this API shall be used in the naming of the API version tag and API version release package. However, as the release package will also include all other APIs of the Sub-project, this may lead to confusion.

An API Sub-project may also decided to release all APIs in the same API family always at the same time with the same API version. In this case,

...

• API (file) in an API Sub-project
• group APIs for meeting / governance purposes (ex-API families) outside of the API Sub-projects, e.g.: 
  1. using a GitHub Working Group folder - but this is being restructure as we speak)
  2. using a CAMARA Wiki page. - seems to be the preferred approach as this is also where meetings are now being managed.
• exception: if an API Sub-project wants to keep multiple APIs in the same API Sub-project:
  • all APIs in this API Sub-project shall have the same version and shall always be released together.
  • the API Sub-project name shall be used instead of the API name in the

...

If later on one API of the API family requires a separate evolution with its own version number, then this API shall be put in its own API Sub-project.

...

• • creation of the API version release assets
  • if any of the APIs needs to evolve its version to a different version than the other APIs in the same API Sub-project, it shall be moved (with its related assets) to its own API Sub-project.

NOTE: We can look at reworking the API sub-project repository structure if needed.

Impact on Wiki, could be either:

• Add the API groupings on the API Sub-group page

API Groupings:

The grouping of APIs into families or other groupings, e.g. by related working groups, can be done easily using a CAMARA wiki page.

This will reduce the number of meetings and reporting load with the increasing number of APIs, and facilitate moving APIs from one family or group to another, or combining APIs from multiple families into into into family.

Actions:

• Each API Sub-projects that contain multiple APIs should
  • decide if it should create separate sub-projects. 
  • If so, decide on the name and request the sub-project creation to ???
  • on the Sub-project pages on the wiki add the list of APIs managed together 
  • Update their wiki page to list the APIs they have release and are maintaining.

See also Herbert's proposal here: Proposal to establish API Families as Working Groups across API Sub Projects · Issue #7 · camaraproject/ReleaseManagement (github.com)