Review guidance for API release PRs

Owned by Tanja de Groot
Last updated: Nov 11, 2024
5 min read

The following sections provide guidance on how to review an API release PR.

Please add questions in the Q&A section as you come across them and addย comments/text for answering them.

Review issues and process

API Sub Projects will request the review of their API release PRs for M3 or M4 approval.

The request is done by adding the camaraproject/release-management_maintainers to the reviewers of the release PR when it is ready for review by the Release Management team.

The Release Management team will create a review issue in which all check points are listed as per the template described in the next section.

For APIs that are targeting to become a stable public API, for M3, the Release Management team may request an additional review by Commonalities and ICM teams.

As a reviewer, if you see a release PR that is nearly ready, add a comment as follows: "Please add @release-management_maintainers to this PR once the PR is ready"

When a release PR review is requested,

  • Create the review issue

  • Assign the issue to a Release Management team member who will

  • Check each task and tick it when done.

  • Check if further review by TSC / Commonalities / ICM is needed (e.g. for targeted stable APIs), and leave issue open until those reviews are marked as done and OK in the review issue

  • For final approval of a release PR, use a comment like: "LGTM from ReleaseManagement."

  • When all tasks and complementary reviews are completed, close the review issue with a comment (in the review issue) on the overall status of the API.

Review issue - usage

A review issue is created by the Release Management team when the review of an API release PR is requested by the API Sub Project for M3 or M4 approval.

A review issue contains actions related to the API review and actions related to the API release.

Review actions

  • API definition files (YAML) (check version in info & servers objects)

  • test file(s) availability

  • changelog updated

  • readme updated (enforce correct release number / API version naming)

  • API readiness checklist(s)

Release actions

The following sections provide more details for the reviewers of API release PRs.

Review actions - details

API definition files (YAML) (check version in info & servers objects)

  • Check Info object

    • version: aligned with the released API version and formatted correctly (per Commonalities)

    • description: check that it

      • contains sufficient in-line API documentation

      • does not use Telco Jargon / abbreviations (non blocking for release if in documentation), e.g. avoids use of

        • "customer", unless explicitly explained what is meant. Instead use as applicable โ€œAPI consumerโ€, (application) โ€œend-userโ€,ย or whatever else is applicable.

        • "Telco/operator/CSP", as also Aggregators, etc. may expose the API. Use a more general term e.g. โ€œAPI exposure platform ownerโ€ as applicable.ย 

        • "subscriber". Use โ€œDeviceโ€ or โ€œEnd-userโ€ (defined as the application user) as applicable

        • โ€œAPI customerโ€: use โ€œAPI consumerโ€ or (application) โ€œend-userโ€, as applicable

      • contains the mandatory text from the section on authentication and authorization from the ICM CAMARA-API-access-and-user-consent.md.

    • contains the x-camara-commonalities version from the Commonalities release referenced in the API readiness checklist.

  • Check servers object has the correct version format e.g. v0.xrc1, v1rc1, v0.x or v1.

  • Check security schemes: check presence and format (OIDC) and scope name format.

  • In externalDocs: this field is optional, but recommend to point to the CAMARA API repository.
    ย  description: Project documentation at CAMARA repository
    ย  url: https://github.com/camaraproject/<api-repository>

  • Ensure that error cases are sufficiently explained in in-line documentation in info.description field.

test file(s) availability

  • all error codes shall be covered by final test scenarios.

  • main error cases for release-candidates / initial versions shall respect Commonalities / documentation / API-Testing-Guidelines.md

changelog updated

  • Check that the PR updates the CHANGELOG.md file as described in the API release guidelines.

  • Hint: For capturing changes, its is recommended to use the GitHub release feature to get the list of all the changes which can then be selected as appropriate and put in the right section (added, changed, etc.) - ask a GitHub expert how to do this by creating a dummy release (guidelines are WIP) and subsequently deleting it.

readme updated (enforce correct release number / API version naming)

  • enforce the correct release number / API version naming

  • avoid the use of the word "customer", unless explicitly explained what is meant. Alternative can be developer, (application) end-user, API consumer, etc. (as applicable).

  • avoid reference to CSPs in case also Aggregators, etc. may expose the API. Use e.g. API exposure platform owner.ย 

API readiness checklist(s)

  • API definition file (see details above)

  • commonalities is respected

    • availability of linting report in release issue

  • ICM is respected (see below)

  • versioning (checked in yaml) is aligned with guidelines

  • documentation (beyond in-line)

    • check for Telco jargon / abbeviations (same as in API definition details above)

  • user stories - check for Telco jargon / abbeviations (same as in API definition details above)

  • basic test files (for M3)

    • cover 2xx response and all error responses (tbc)

  • enhanced test files (for M4)

    • cover all error responses

  • release numbering is aligned with guidelines

  • changelog (see details above)

  • certification - for stable public APIs - check GSMA reference.

Release actions - details

API release tracker available on wiki

Go to the API Sub Projectโ€™s home page on the wiki and check the availability of the API release tracker and its contents.

Check that the API is visible on the targeted meta-release plan indicated in the tracker. If not, indicate to the API Sub Project to update the tracker page with the appropriate meta-release label.

Review comments addressed (by Sub Project)

Check the tick box when the review comments provided by the Release Management team have been addressed by the API Sub Project.

Release PR approved (on behalf of Release Management)

Approve the release PR by putting a comment in the release PR like: โ€œLGTM from ReleaseManagementโ€.

PR merged (by Sub Project codeowner)

Check the tick box when the release PR has been merged.

Release created within GitHub (by Sub Project codeowner)

Check the tick box when the release has been created.

Release Tracker updated (with creation date of the release and the release tag link)

Check the tick box when the release tracker has been updated with the new release and the date

In case of a maintenance release, update the CAMARA home page

In case of maintenance release only: add a PR on https://github.com/camaraproject/.github/blob/main/profile/README.md created (by Release Management) and merged (by CAMARA admin).

Commonalities and ICM review checks

For APIs that are targeting to become a stable public API, the Release Management team shall request a review by Commonalities and ICM teams.

Commonalities team review - details

Most checks are covered by the Release Management review.

ICM team review - details

These points are taken from:ย https://github.com/camaraproject/IdentityAndConsentManagement/issues/189#issuecomment-2315026741 )

Ref for examples:ย https://github.com/camaraproject/SimpleEdgeDiscovery/blob/r1.2/code/API_definitions/simple-edge-discovery.yaml

Check the ICM-definedย info.descriptionย template (Authorization and Authentication section). Reference
Check the use of openIdConnect forย securitySchemes.ย Reference
Check the use of theย securityย property according to ICM definitions.ย Reference
Error codes are defined by Commonalities e.g. INVALID_TOKEN_CONTEXT.
However, ICM could check the definition of a 403 INVALID_TOKEN_CONTEXT if it applies to a specific API (e.g. APIs using device object or phoneNumber in the API request). Reflects an inconsistency between information in some field of the API request and the access token.
โš ๏ธย OK with comments. The API specification has its own sectionย Identifying the Device. The API specification doesย notย include theย recommendedย section called "Identifying a device from the access token" inย info.descriptionย that provides a detailed description of the expected handling of theย deviceย object in the API request as it relates to the access token. It is specified inย Appendix A: info.description template for device identification from access tokenย and it is required for APIs that use theย deviceย object in the API requests.
Verify that there is no unexpected leakage of users' personal information, such as API responses containing identifiers or information beyond the API functionality.ย 

Example: OK, the API can be used to verify a phone number. Please seeย API misuseย Commonalities#259. Ifย Phone-Numberย is part of the API request then response tells the API consumer the same as a request to NumberVerification does.

For APIs including a device object, check that Appendix A of the API-Design-Guidelines.md is respected:ย info.descriptionย template forย deviceย identification from access token

Q&A

  • Who can approve the M3 release PR ? Code Owners after RM approval is noted in the release PR or its issue.ย 

  • When to create a RM review issue ? When the release-management_maintainers list is included as a reviewer in a release PR.ย 

  • When do I tick a review issue task ?

    • Review actions: tick after checking the related file(s) and putting the review comment(s) in the PR/PR issue about the(se) files. Also put just OK for the file if no comments.

    • Also put a comment in the review issue with the major review comments and the overall state of the API.

    • Release actions: tick when task is done.

  • When do we close the review issue ? When all tasks in the review issue are ticked as done. Close as completed.

  • Should we add a milestone label so we can filter on it later ?ย 

  • How to know if an API is covered by RM ?ย  Once a review issue is created it links to the PR. and should be visible in the comments.

  • Is there a way to know if an API requires consent request ? No, this is local regulation. It is covered when using the security scheme and the scope rules.

Open questions

  • should the test files contain the API version ? e.g.ย Feature: CAMARA Call Fowarding Signal ย API, v0.1.0 - Operation call-forwardings - is it required to include the version (as people forget to update it) As the tests are in the same release package, can the version number be avoided in the test features ?

  • can we automate test generation for an API - which tools ? - which ensures that all API spec errors/cases are covered by the tests ?

  • add guideline to use error codes in scenario names ?