Release Management FAQ

Please add your questions to this page.

How to create a new API in CAMARA ?

A new API is first submitted to the API Backlog repository according to the steps described here: Submission of a new API proposal

After discussion in the API backlog team the API proposal is submitted for approval to the TSC.

When approved, the repository for developing the API is created. This may be done as a standalone Sandbox or under an existing API Sub Project. The full lifecycle of API repositories is described here: Governance: API-Onboarding-and-Lifecycle

Once you have your repository, the API development can begin and you can start the release cycle.

The guidelines to prepare an API release are described here:

• In GitHub: API_Release_Guidelines.md, especially the section on Releasing an API step-by-step.

• (or same with some more examples) on the Wiki: https://lf-camaraproject.atlassian.net/wiki/x/jine

Additional notes:

• there is no need to join the Release Management meeting for doing an API release, nor to present the API s there.

• an alpha release of the API is done internally in its repository under the API Sub Project

• no review by the Release Management team is required for alpha-releases (but can be requested as indicated by Herbert)

• once an API is sufficiently developed, for M3, the first release-candidate of an API is prepared and the review of its release PR is requested to the Release Management team

• for any further questions you can

  • look at the FAQ on the Wiki (this page) - you can add your question there and notify by email.

  • email to wg-release-management@lists.camaraproject.org

  • create a GitHub issue in the Release Management Issues list

  • if all else fails, send an email to tanja.de_groot@nokia.com and herbert.damker@telekom.de

What are the prerequisites to release a stable version ?

• a previous public API version is available at least 1 certified implementation

• all release assets are available as per the API readiness checklist

• there were not too many changes wrt the previous version

• it is expected to not have any breaking changes in the next 2 meta-releases

• the TSC approves it 

Creating a maintenance release / patch API version for Fall24 APIs

Although the Fall24 meta-release is now closed, there is no time limit to release patches of APIs if they are needed.

Develop the patch (and any future patches) on a dedicated maintenance branch: for details, see PATCH-update section in the API release process.

What to do if I accidentally released my API before Release Management review ?

You can easily create a next release rx.y+1 at any time. 

In this case, create a "Release Management review" issue in your Sub Project and assign it to a release manager (tanja, samuel, herbert, jose luis, rafal) 

If there is a change required, this will be put in the comments in the issue and the Sub Project team can start a new PR to include the changes.

NOTE: If there are substantial change the version should go back to wip in a dedicated PR and release later. If it concerns content changes to the API yaml file, then also the API version should be increased in-line with the type of change (most likely MINOR ot PATCH).

The Sub Project can decide when to merge the PR and create the new release.

What to do in case of codeowner absence (only during holidays) ?

You should have at lease 2 or preferably 3 codeowners

However in case of issues, if consent of the team seems OK, an admin can do a merge (email: adm@camaraproject.org)

HINT: How do I check that links in my Sub Project are defined correctly ?

To  check links in the repo, create a (test)branch, tag it with the targeted release tag name.

It will give errors if links are not aligned. Then delete the (test)branch.

Update the links latest in the release PR.

M3: yaml info object: How to add reference to commonalities and remove 'termsOfService' and 'contact' fields ?

In your API yaml file, in the info object, under the version field, please make sure to add: x-camara-commonalities: 0.4.0

The fields `termsOfService` and `contact` shall be removed. They are put by API providers for their implementation if they so desire.

example:

info:

  title: One Time Password SMS

  description: |-

    Service Enabling Network Function API to send short-lived OTPs (one time passwords) to a phone number via SMS and validate it afterwards, in order to verify the phone number as a proof of possession.

    # Relevant  Definitions and concepts

    - **NaaS**: *Network-as-a-Service* model where Telco Network resources are exposed to third parties through APIs. In this particular API, One Time Password is exposed following this model.

    - **OTP**: *One Time password* is a one-time authorization code (OTAC) that is valid for only one login session or transaction.

    # API Functionality

    It enables a Service Provider (SP) to send an OTP code by SMS and validate it to verify the phone number (MSISDN) as a proof of possession.

    # Resources and Operations overview

    This API currently provides two endpoints, one to send an OTP to a given phone number and another to validate the code received as input.

    # Authorization and authentication

    [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token.

    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

  version: 1.0.0-rc.1

  x-camara-commonalities: 0.4.0

  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

M3: yaml servers object: How to put the API version in the URL ?

The servers object should look like this (API Guidelines section 11.1):

servers:

  - url: '{apiRoot}/yourapiname/v0.yrc1' (for initial release or v1rc1 in case of stable release)

    variables:

      apiRoot:

        default: http://localhost:9091

        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`

How to maintain the API release tracking page for a new meta-release

The API release tracking page allows to list all the Sub Project’s APIs grouped per meta-release.

• It requires that there is an API release tracker page for each API version

• Each API release tracker page shall get the label of the meta-release it is part of, e.g.: camara-spring25, camara-fall25, etc., or camara-other for APIs outside the meta-release.

• A “page properties report” macro is then used to

  • select the pages by label

  • to extract information from the API release tracker pages by configuring the macro with a selection of the “Columns to show” in the “Options” section. The Columns correspond to the header fields of the row in the page properties table on the API release tracker page.

  • The “Columns to show” is a comma separated list of fields as follows:

    • v2 (latest) (Spring25 and later, and Other APIs): M3 date, M4 date, API version, Pre-release, Public release

    • v1 (Fall24) : M3 date, M4 date, API version, pre-release tag, M5 date, public-release tag

To add a new meta-release to the API release tracking page, or a section on “Other APIs” outside the meta-release, then do the following:

• add a Header 2 section title with the meta-release name, e.g. Spring25, Fall25, etc.

• add the “page properties report” macro

• configure it with the meta-release label and the “Columns to show” v2 (see above)

How to view the yaml file of a not yet published release ?

• open a Swagger UI (e.g. by clicking on the link in the readme) - this will open with a failure as the release does not exist yet) - keep the window.

• go to the yaml file in the release PR. click on "raw". in that view, copy the url at the top

  • it should be: https://raw.githubusercontent.com/camaraproject/$APIRepositoryName$/rx.y/$fpath to API yaml file$

• paste this url into the swagger window. it should load correctly

How to add links to docs / pictures in a yaml file

When viewing the api yaml in the swagger UI, a local reference to a documentation file or picture does not work, as the context is http://github.io , not the API repository.

The link in the API yaml should be formatted as a full release link in the right context as follows:

• [required file](https://raw.githubusercontent.com/camaraproject/$APIRepositoryName$/rx.y/$fpath to required file$)

• in case of a picture. prefix the above reference with “!”

To check correct display:

• update the link in the yaml file to the full release link of the referenced file (.md or .PNG, etc)

• view the yaml file in swagger as above

• check if the updated reference works