1 | API Versioning (Alpha/Beta vs Semantic...) | Consider including Alpha and Beta labels to API versions #13 | 2024-05-13 (tdg) Decoupled release name/number (rx.y) from API version numbering - see API Release Numbering 2024-04-12 (tdg) Decoupling release name/number (rx.y) from API version numbering - see Multiple APIs in one Sub-project 2024-03-27 (tdg): use of alpha API versions for rapid development and release-candidate API versions. No use of beta API versions. These version extensions are only used inside CAMARA, not in API versions part of a meta-release. API versions that have been release as part of a meta-release shall follow the major.minor.patch interpretation of semver 2.0 - see Release management & versioning - proposal - CAMARA Project - Confluence 2024-03-05: Take:
There's a debate about the necessity of using Alpha and Beta labels, with some suggesting that pre-release versions could follow semantic versioning without additional labels.
The use of Alpha and Beta labels may not align perfectly with CAMARA's release processes, as APIs may not remain in draft states for extended periods
Some thoughts:
Including alpha and beta labels signals to API consumers that certain features may be subject to change. This early communication helps manage expectations and encourages users to provide feedback during the development process.
For the purposes of API Lifecycle Management, Alpha and beta labels can be useful for indicating the development stage of an API. This information helps API consumers understand the stability and maturity level of the API, allowing them to make informed decisions about adoption. However, it will require a defined versioning scheme across all sub-APIs/projects and commonalities and ICM may have to adopt to similar versioning scheme.
What's next:
We need to define and agree upon the criteria that qualify an API as alpha, beta, or stable.
If the proposal involves integrating alpha and beta labels with Commonalities and ICM, we need to have a defined and agreed-upon mechanism for handling these labels across the ecosystem.
First we have to define the target commonalities and ICM for the Meta Release.
Q1: What is the target commonalities and ICM for the Meta Release?
Once we know what the target commonalities and ICM for Meta Release is (e.g., let's say it is 0.2.0), then a possible option is to introduce a new attribute (e.g., let's it is commons-version:)
The proposal will be to insert an additional attribute per openapi standards: in all sub-API yaml files for the sub-APIs and set it to the commonalities version. So, it will be set to: x-commons-version: 0.1.0 to reflect the current commonalities version. Then, when the commonalities version is settled for the Meta Release (e.g., let's it is 0.2.0), we would have all the sub-APIs update the value of the newly introduced attribute to point to the Meta release version. In this case, it will be (as an example) x-commons-version: 0.2.0
Both commonalities and ICM should be on par when it comes to the Meta Release version, so if commonalities is targeting 0.2.0, then the profile version of ICM (and/or any future APIs that may be added in ICM) will have the same version association of commonalities.
Scenarios
1. ICM documentation had to be updated, or a new OIDC profile had to be created. In that case, ICM first gets a candidate release, once all PRs go into that candidate release are merged, then ICM will get alpha tag. At that point Q2: Do we advance the Commonalities version? or do we wait until a beta or stable version of ICM before increasing the Commonalities?
2. Commonalities gets a breaking change, and updates the content, in that case Q3: do we increase the ICM to match the CAMARA version?
given the artifacts that will be coming out of ICM, once there is a stable version of ICM artifacts, Q4: should we merge that into Commonalities (e.g. prior to first meta release) and that way there is only 1 repo to be considered.
Both target Commonalities and ICM versions for the Meta Release will point to the target Camara release project (e.g., 1.0.0)
|
|
| API Versioning - Aggregation #14 | 2024-03-27 (tdg): use of minor versions in URL only for API versions with x=0. - see Release management & versioning - proposal - CAMARA Project - Confluence. Proposal: A page will be added to the CAMARA Wiki where a CSP can indicate which public-release API versions they support. In addition, CSP shall interact with the channel partner on the lifecycle of their API versions and the maintenance of a given API version. 2024-03-05: Take:
The problem identified in the API versioning strategy is that using only major versions in the API path can lead to compatibility issues when aggregating across different CSP implementations with varying minor versions. The concern is that minor versions are not forward-compatible, and there might be differences in response structures or formats between different minor versions.
The suggested solution is to include the minor version in the API path. The proposal is to aggregate at the minor version level (e.g., v1.1 or v1.0), and each CSP should publish its supported versions in a well-known location. Additionally, CSPs should follow an agreed-upon lifecycle for supporting minor versions
In the provided examples, the minor version is explicitly included in the API path. It allows for clarity in distinguishing between different versions, especially when making changes to existing endpoints. The ASPs can then adapt their requests based on the client's minor version, ensuring compatibility and preventing issues with changes in response structures or formats.
Last comment was: " "Sorry I missed this - the problem is not with adding new endpoints, but making changes to existing endpoints, like adding new fields or renaming fields or changing types, these have all happened in v0; it's not possible to make a v0 SDK.
When we get to v1 we should not be making non-breaking changes in minor versions of course." "
Thought:
The challenge mentioned in the comment is that making such non-breaking changes in minor versions poses difficulties for SDKs, especially when transitioning from v0 to v1. In the transition from v0 to v1, where non-breaking changes were made in v0, creating a v0 SDK might be challenging due to the historical changes in the v0 versions.
So, creating a transition guide for SDK developers, outlining the changes introduced in each minor version and learly state which versions are backward-compatible and provide guidance on updating SDKs to accommodate non-breaking changes could potentially help.
A sub-APIs will have their own versions (which is not always the same), so any non-breaking changes can continue to be captured in the existing versioning scheme of the sub-APIs. The proposed solution in 1 could be also applicable here. |
2 | API Family versioning | How to manage version for a API family release #12 | 2024-03-27: API families shall not be version managed only APIs. See: Release management & versioning - proposal - CAMARA Project - Confluence. Existing RM issue #7: Proposal to establish API Families as Working Groups across API Sub Projects #7 opened on Nov 14, 2023 by hdamker. Proposed text to add to this issue: decide on one of the following choices: creation of a sub-project per API the owning team manages multiple sub projects. in addition: create a working group that links to the list of API subgroups - or just a confluence page with a table use folder per API with focused release packages
2024-03-05: Take: 1. Some contributors express discomfort and confusion with using numerical versions for family releases, especially when API versions are also involved.
2. Discussions around overcomplicating release tags with terms like "release" or adding the year. Preference for a simpler approach.
3. Concerns about using version numbers like v1.x, v2.x for releases containing APIs in v0.x, which might give the impression of major releases rather than intermediate milestones. There was a reference to a consolidation issue (#9) where the use of semver for groups of API endpoints is discussed, emphasizing a preference for simpler conventions.
Expected Action: A common agreement is sought for API family release management
Per the notes in 1., there could be three different options to go about this:
Option 1: Adding an Attribute Under info:
openapi: 3.0.3
info:
x-CommonsVersion: 0.3.0
In this option, x-CommonsVersion is a custom extension property added under the info section to represent the commonalities parent project version.
Option 2: Using Components:
openapi: 3.0.3
components:
x-CommonsVersion:
version: 0.3.0
In this option, a separate x-CommonsVersion section is added under components that points to the commonalities parent project.
Option 3: Embedding in a Custom Top Level Field:
openapi: 3.0.3
x-CommonsVersion:
version: 0.3.0
In this option, a custom top-level field (e.g., x-CommonsVersion) is added with the associated version information under it. |
3 | Release Branches | Development and Release Branches #10 | 2024-03-27: See the proposal here: Release management & versioning - proposal - CAMARA Project - Confluence. API can do minor and patched on a maintenance branch. New open issue is on how to handle the alpha API version: tag, branch, other: see: Multiple APIs in one Sub-project 2024-03-05: Take: Input: Problem identified is about Main and Release Branches - that the Camara Versioning Guidelines Doc did not expliciityly specify on which branch development is done. Reporter proponed 2 options.
Popular vote was for the Second Option which supports that all development should be done on the Main Branch, and this branch will be WiP. When ready, a Release Tag and Release Branch is created for consolidation. Release branch is then the one to used by ext developers (stable branch).
'Option 2:
the Main Branch is where the External Developer can find the work in progress. It is meant for development. When the work is consolidated a Release Tag is created and a Release Branch is created. Considering an API Family with more APIs inside, a Release Tag and a new Release Branch is done when all the APIs are completed.
the Release Branches is where the External Developer can find a stable version.'
This option however opens up another topic - (i) Versioning of the Release branch (ii) What happens if an API Family has more than one APIs and (Iii) How to version Maintenance Release.
API Family management and versioning needs to be discussed and clarified. For example, what will be the Release Tag/Branch of an API family if the API inside has different versions. |
5 |
| Add guidance for Info object in apis #15
CLOSED in RM | 2024-05-14: the below was put in issue #15 which will be transferred to Commonalities. Proposed content for the Info field of the API definitions. To be put in the issues list as a follow-up on listed issue #13 and then request for comments. This should be added to the API guidelines document in the Commonalities WG. - needs a PR to be done
---- proposal with some open options ---- title: <human readable API name> without “API” in it, e.g. "Number Verification" description: <text explaining the API, part of the API documentation> e.g. "This API allows to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared. ..." - this should include a section on the authentication version: 1.0.1 - Aligned to SemVer 2.0 according to CAMARA design guidelines termsOfService: http://example.com/terms/ - to be replaced by the provider's terms contact: name: <API provider contact name> - check if we can put variables here url: <API provider url> email: <API provider contact name> license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html
I checked: variabled seem to be used only in servers object. Add both to API Guidelines and to the Common example file
info:
title: Number Verification
description: |
This API allows to verify that the provided **mobile phone number** is the one used in the
device. It verifies that the user is using a device with the same *mobile phone number* as it
is declared
version: 0.2-alpha.1
termsOfService: http://example.com/terms/
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
|