API description checklist compliance review for Sim Swap marketing page

[anthorange]

Problem description
This issue is based on the Camara Marketing “Checklist for API description review”:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

The Sim Swap API page reviewed:
https://camaraproject.org/sim-swap/

The page has checklist compliance gaps for:

• API Description (the image is only illustrative)
• Use Cases (missing GSMA Use Case Library links)
• Sub Project Wiki (incorrect prefix)
• API Version(s) and Release Date(s) (format normalization issues / date or order issue)

Expected action
Please update the Sim Swap API documentation page so it matches the checklist by applying the following corrections:

1. API Description

• The image is currently illustrative and does not clearly represent a “typical use case” workflow/value for developers (as expected by the checklist).

2. Use Cases

• Add GSMA links that match appropriate use cases: e.g. https://www.gsma.com/solutions-and-impact/gsma-open-gateway/gsma_resources/fraud-detection-in-mobile-insurance-claims/.

3. Sub Project Wiki

• The correct prefix is "Sub Project Wiki:" (current prefix: "SubProject Wiki:")

4. API Version(s) and Release Date(s)

• Version 0.4.0 does not match exactly the checklist format (no meta-release present).
• v1.0.0 date (04.04.2025) looks incorrect compared to meta-release (Fall24). It should be a dd.mm.2024 instead of 2025.
• Verify the ordering rule from the checklist (“newest at the bottom”) based on release date. For example, re-check v1.0.0 against the listed dates to ensure ordering consistency.

Additional context
Checklist reference:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

Reviewed page export:
https://camaraproject.org/sim-swap/

[MarkusKuemmerle]

Hello,

the CAMARA outreach team is currently reviewing all the API descriptions to improve it and make it attractive for customers and developers. There is some confusion how to handle and solve the findings. I would like to give the following recommendations:

• Findings in the text of API description, Use Cases, Benefits: These should be solved by the Sub Project, changes should be documented in the API description Wiki page, and then the Sub Project should open an issue in the Marketing repo to change the website. This follows the defined process description to change the website.

• Findings in the visuals: The Sub Project should give instructions to improve the visuals following the criterias defined in the checklist. The instructions also can be included in the wiki page and addressed to the outreach team by issue in the Marketing repo. We plan to ask the LF creative team to generate new visuals for us based on these instructions.

• Findings on the right column (with all the links): Reviewers should put these findings in the review xls and not in the issue. Sub Projects cannot solve it. The CAMARA outreach team is taking the findings from the xls and is changing the website.

So please work on 1. and 2. and ignore 3. and 4. in the first comment above.

Hope that helps, Markus

[albertoramosmonagas]

Thanks @MarkusKuemmerle, @anthorange, that clarification helps.

I create another wiki description according with the changes suggested: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/807632909/Sim+Swap+API+Description+v2. This is a proposal for the @camaraproject/sim-swap_codeowners to review.

For the visuals, I've added one based on this logic:

I will add instructions for replacing the current illustrative image with a workflow-based visual. The proposed visual should show the typical flow: user initiates sensitive action → application calls CAMARA SIM Swap API → operator checks latest SIM change → API returns swapped or latestSimChange → application applies risk-based action such as allow, step-up authentication, alert, review or block.

For the findings related to the right column, such as Sub Project Wiki prefix and API versions / release dates, I understand these should be handled by the CAMARA outreach team based on the review XLS, so we will not address them in this issue.

[bigludo7]

Thanks @albertoramosmonagas
We need to add the third endpoint in the description probably? WDYT?

[albertoramosmonagas]

Hi @bigludo7, since it's optional and I'm not quite sure how the rest of the group plans to implement it, I'd prefer not to do it.

[bigludo7]

@albertoramosmonagas OK ! As this is still a 'exploratory' endpoint I'm fine to not yet introduce it in the documentation.... btw we can update the documentation anytime so if this new end point has success we can update the doc without waiting for an annual release. I will comment this tomorrow (July 16) in our call.

[bigludo7]

@albertoramosmonagas @MarkusKuemmerle Alberto was very smart to no introduce the third endpoint in the API description as we removed it now !
For me the page are correct. We will have to update https://camaraproject.org/sim-swap/ after the next meta release once we have the date.