Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release r1.1 (Release Candidate) #71

Merged
merged 7 commits into from
Feb 19, 2025
Merged

Release r1.1 (Release Candidate) #71

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
83cf3cd
Release r1.1 (Release Candidate)
PedroDiez Jan 15, 2025
8166865
remove_README.md_from_API_definitions
PedroDiez Jan 16, 2025
a49c8c5
alignment_with_commonalities_r2.2
PedroDiez Jan 24, 2025
0bb7f2a
updates_after_RM_review
PedroDiez Feb 13, 2025
56e7554
align_with_main
PedroDiez Feb 14, 2025
7c2df3c
updates_over_README.md
PedroDiez Feb 18, 2025
aa4c3f8
updates_over_API_spec
PedroDiez Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 59 additions & 4 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,71 @@

## Table of Contents

- [r1.1 - rc](#r11---rc)
- [v0.1.0](#v010)

**Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.**

The below sections record the changes for each API version in each release as follows:

* for an alpha release, the delta with respect to the previous release
* for the first release-candidate, all changes since the last public release
* for subsequent release-candidate(s), only the delta to the previous release-candidate
* for a public release, the consolidated changes since the previous public release

## r1.1 - rc

## Release Notes

This release contains the definition and documentation of
* Blockchain Public Address v0.2.0-rc.1

The API definition(s) are based on
* Commonalities v0.5.0-rc.1
* Identity and Consent Management v0.3.0-rc.1

## Blockchain Public Address v0.2.0-rc.1

**Blockchain Public Address v0.2.0-rc.1 is the first release-candidate version for v0.2.0 of the Blockchain Public Address API.**
- **This version contains significant changes compared to v0.1.0, and it is not backward compatible:**
- Refactor `retrieveBlockchainPublicAddress` endpoint to use an HTTP POST request
- Error model aligment with commonalities, which implies use of normalization values (i.e. enums) for `status` and `code`
- Removal of `5XX` errors


- API definition **with inline documentation**:
- [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/r1.1/code/API_definitions/blockchain-public-address.yaml&nocors)
- [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/r1.1/code/API_definitions/blockchain-public-address.yaml)
- OpenAPI [YAML spec file](https://github.com/camaraproject/BlockchainPublicAddress/blob/r1.1/code/API_definitions/blockchain-public-address.yaml)

### Added
* Added new `blockChainNetworkId` Aleph Zero Network in https://github.com/camaraproject/BlockchainPublicAddress/pull/60.
* Added API Readiness Checklist in https://github.com/camaraproject/BlockchainPublicAddress/pull/68.
* Added initial testing plan in https://github.com/camaraproject/BlockchainPublicAddress/pull/70.

### Changed
* API aligment with Commonalities (Fall24 aligment) in https://github.com/camaraproject/BlockchainPublicAddress/pull/58.
* Refactor `retrieveBlockchainPublicAddress` endpoint to use an HTTP POST request (avoid phoneNumber as query param) in https://github.com/camaraproject/BlockchainPublicAddress/pull/60.
* Updated User Story file name in https://github.com/camaraproject/BlockchainPublicAddress/pull/67.
* Updated `# Authorization and authentication` section from ICM guideline in https://github.com/camaraproject/BlockchainPublicAddress/pull/69.
* Error model aligment with commonalities (Spring25 aligment). Normalization values (i.e. enums) for `status` and `code`. In https://github.com/camaraproject/BlockchainPublicAddress/pull/69.

### Fixed
* Phone number description to be aligned with Commonalities in https://github.com/camaraproject/BlockchainPublicAddress/pull/69.

### Removed
* Removed `5XX` errors in https://github.com/camaraproject/BlockchainPublicAddress/pull/69.

## New Contributors
* N/A


**Full Changelog**: https://github.com/camaraproject/BlockchainPublicAddress/compare/v0.1.0...r1.1

## 0.1.0

## Release Notes

**Initial baseline contribution**
- API [definition](https://github.com/camaraproject/BlockchainPublicAddress/tree/release-0.1.0/code/API_definitions)

Expand All @@ -17,22 +76,18 @@
- there are ongoing discussions so API evolution is expected.

### Added

* Initial version with three endpoints:
* New endpoint `retrieveBlockchainPublicAddress`
* New endpoint `bindBlockchainPublicAddress`
* New endpoint `deleteBlockchainPublicAddress`

### Changed

* N/A

### Fixed

* N/A

### Removed

* N/A

## New Contributors
Expand Down
25 changes: 17 additions & 8 deletions README.md
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 10. repleace "API family" by just "APIs", as the API family concept no longer exists in CAMARA.
If this API and its repository is part of a Sub Project? you should mention it here as well

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, changed to "APIs".

In this case the Sub-proyect equals to The CAMARA Repository

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 14.: "telco service providers have the opportunity to provide 3rd parties with the following capability"
Suggest to change to: "API providers offer API consumers the following capability"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, done

Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,23 @@ Repository to describe, develop, document and test the Blockchain Public Address
* Started: June 2023

## Release Information
* Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.
* **The first initial release and version of Blockchain Public Address API is 0.1.0 and is available within the [release-0.1.0 branch](https://github.com/camaraproject/BlockchainPublicAddress/tree/release-0.1.0)** There are expected changes in upcoming releases. It is addressed for early implementations, but not a stable version yet.
* API definition of Blockchain Public Address API is 0.1.0 (with inline documentation):
- OpenAPI [YAML spec file](https://github.com/camaraproject/BlockchainPublicAddress/blob/release-0.1.0/code/API_definitions/blockchain_public_address.yaml)
- [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/release-0.1.0/code/API_definitions/blockchain_public_address.yaml&nocors)
- [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/release-0.1.0/code/API_definitions/blockchain_public_address.yaml)
* All releases and pre-releases are available here https://github.com/camaraproject/BlockchainPublicAddress/releases
* For changes see [CHANGELOG.md](https://github.com/camaraproject/BlockchainPublicAddress/blob/main/CHANGELOG.md)
<!-- Use/uncomment one or multiple the following options -->
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You may remove the commented lines (as you used them below

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, done

<!-- Pre-releases of this sub project are available in https://github.com/camaraproject/BlockchainPublicAddress/releases -->
<!-- The latest public release is available here: https://github.com/camaraproject/BlockchainPublicAddress/releases/latest -->
<!-- For changes see [CHANGELOG.md](/CHANGELOG.md) -->
* Note: Please be aware that the project will have updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**.

* **The Release [r1.1 - rc](https://github.com/camaraproject/BlockchainPublicAddress/blob/main/CHANGELOG.md#r1.1---rc) for the Blockchain Public Address APIs Family is available.**
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there should never be a "main" in a link, only the release (in this case "r1.1") so this link should be:

** The Release r1.1 for the Blockchain Public Address APIs is available.

and I would put it just under the title.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to make it explicit: the link to the release will be https://github.com/camaraproject/BlockchainPublicAddress/releases/tag/r1.1 (and will be valid only after the release got created)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, i indicated wrong link

<br>This is a release candidate. Until the public release there are bug fixes to be expected. The release candidate is suitable for implementors, but it is not recommended to use the API with customers in productive environments.

* The release **r1.1 - rc** is available in [r1.1](https://github.com/camaraproject/BlockchainPublicAddress/tree/r2.1), and includes the following APIs:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* The release **r1.1 - rc** is available in [r1.1](https://github.com/camaraproject/BlockchainPublicAddress/tree/r2.1), and includes the following APIs:
* The release **r1.1 - rc** is available in [r1.1](https://github.com/camaraproject/BlockchainPublicAddress/tree/r1.1), and includes the following APIs:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link to the release will be https://github.com/camaraproject/BlockchainPublicAddress/releases/tag/r1.1

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, done

* API definition of Blockchain Public Address API is 0.2.0-rc.1 (with inline documentation):
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* API definition of Blockchain Public Address API is 0.2.0-rc.1 (with inline documentation):
* API definition of Blockchain Public Address API is version 0.2.0-rc.1 (with inline documentation):

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok, done

- [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/r1.1/code/API_definitions/blockchain-public-address.yaml&nocors)
- [View it on Swagger Editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/BlockchainPublicAddress/r1.1/code/API_definitions/blockchain-public-address.yaml)
- OpenAPI [YAML spec file](https://github.com/camaraproject/BlockchainPublicAddress/blob/r1.1/code/API_definitions/blockchain-public-address.yaml)

* Other releases of this sub project are available in [BlockchainPublicAddress Releases](https://github.com/camaraproject/BlockchainPublicAddress/releases)
* For changes see [CHANGELOG.md](/CHANGELOG.md)

## Contributing
* Meetings
Expand Down
1 change: 0 additions & 1 deletion code/API_definitions/README.MD
View file
Open in desktop

This file was deleted.

4 changes: 2 additions & 2 deletions code/API_definitions/blockchain-public-address.yaml
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line 8: the concept NaaS is introduced but it is never used. Please remove this concept, also because it is telco focused, not useful for the API consumer, and CAMARA should not make any assumptions about how an API is managed (it just cares about the API definition.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fully agree, removed

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Error handling:
as this API carries a PhoneNumber, I think the Commonalities section on related errors needs to be applied. Did you check it ?
see: https://github.com/camaraproject/Commonalities/blob/r2.2/documentation/API-design-guidelines.md#62-error-responses---device-objectphone-number

BTW you seem to have the 403 ACCESS_DENIED error defined twice with the same example message.

  • once inside the PermissionDeniedForBlockchain403
  • and in the Generic403

if you mean them to be different, maybe change the example message and also explain the errors in the info.description section.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First point is commented here

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding this: BTW you seem to have the 403 ACCESS_DENIED error defined twice with the same example message.

I think the model is compliant to Commonalities. Considering it needs some adaptations based on API functionality.
I will add some info in the related endpoint (Perform a binding). Let me explain from the high-level point of view:

For Retrieving/Unbinding it has been defined the regular 403 (PERMISSION DENIED)
For Binding there is the additional case where the indicated BlockChainNetworkId is not allowed by busines rules. That is the reason to define a new Response model -> PermissionDeniedForBlockchain403 that both covers (PERMISSION DENIED and such a case).

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line 18: "Notice that the mobile phone number used as input may even not belong to the same Telco Operator exposing the API. It is expected a communication between Telco Operators to resolve the Blockchain Public Address(es). For example a Telco Operator will receive the request, identify the Telco Operator which owns the mobile phone number, and forward the request using a 2-legged approach to contact the other Telco Operator."

This description is focused on the API provider, not the API consumer who does not want to know about the complexity between Telco's etc.

I would drop this whole paragraph

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, done, understood the rationale.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Logically line 19 should go before line 17

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line 19: Change "sub" to "user

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will rephrase that.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

line 22: before this section, you need tto include the mandatory text from Commonalities from this section:
https://github.com/camaraproject/Commonalities/blob/r2.2/documentation/API-design-guidelines.md#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a template issued for APIs that may work in 2/3 legged in order to avoid the API Misuse implicitly exposing Number Verification feature.

The template has not been indicated because it is not the case for Blockchain Public Address. The rationale under it is indicated below:

  • Perform a binding is a only 3-legged mode operation, and "phoneNumber" indication is required to enforce the procedure to ensure the binding process
  • Remove a binding does not use "phoneNumber" as a input
  • Retrieve a list of bindings may work in 2/3legged mode and always requires "phoneNumber" as an input to perform the logic.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

on the endpoint description: please make sure that what is written about 2 legged / 3 legged is in synch with the lates commonalities.
You may also explain here any API specific errors returned.

see also https://github.com/camaraproject/Commonalities/blob/r2.2/documentation/API-design-guidelines.md#appendix-a-normative-infodescription-template-for-when-user-identification-can-be-from-either-an-access-token-or-explicit-identifier

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed in above comment

Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,13 @@ info:
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: wip
version: v0.2.0-rc.1
x-camara-commonalities: 0.5
externalDocs:
description: Product documentation at Camara
url: https://github.com/camaraproject/BlockchainPublicAddress
servers:
- url: "{apiRoot}/blockchain-public-address/vwip"
- url: "{apiRoot}/blockchain-public-address/v0.2rc1"
variables:
apiRoot:
default: http://localhost:9091
Expand Down