feat: moving the fx changes pr from documentation repo here #129

elnyry-sam-k · 2024-04-25T10:53:11Z

to the ML specification repo on Behalf of Michael Richards for the FSPIOP SIG

…ion repo on Behalf of Michael Richards for the FSPIOP SIG

henrka

Please find my comments after a first read of the actual changes.

fspiop-api/documents/API Definition v2.0-alpha.md

Addressing PR comments

Responses to Henrik's comments

fspiop-api/documents/API Definition v2.0-alpha.md

henrka · 2024-07-15T13:43:06Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -2933,22 +2933,20 @@ Either the payer DFSP or the payee DFSP may request currency conversion. If the

 ##### 6.12.2.1 Conversion Quote Expiry Details

-In the same way as with an ordinary quotation (see [Section 6.5.2.1](#6521-quote-expiry-details) above), the requesting DFSP should include an expiry time for the quotation.
+In the same way as with an ordinary quotation (see [Section 6.5.2.1](#6521-quote-expiry-details) above), the FSP requesting the quotation should include an expiry time for the quotation.


Suggesting to remove "above", as using "above" might increase the required maintenance of the document (a move might place the section below instead)..

fspiop-api/documents/API Definition v2.0-alpha.md

Responses to Henrik's review 20240715

henrka

Please also fix the Introduction and Table 6, 7, and 8 as discussed on chat.

fspiop-api/documents/API Definition v2.0-alpha.md

Responding to comments from Henrik Karlsson.

Added links to specification sections from introduction

Changes to support ULIDs as unique identifiers as well as UUIDs

Add new header parameter and changes to accept and content-type parameter syntax.

henrka · 2024-12-16T13:41:47Z

Not part of this change, but suggesting to update the following in Section "2. Introduction":

Version 1.0 of the API is designed to be used within a country or region, international remittance that requires foreign exchange is not supported. This version also contains basic support for the Interledger Protocol, which will in future versions of the API be used for supporting foreign exchange and multi-hop financial transactions.

To (removing part with "future versions":

Version 1.0 of the API is designed to be used within a country or region, international remittance that requires foreign exchange is not supported. This version also contains basic support for the Interledger Protocol.

henrka · 2024-12-16T13:52:25Z

Table 8, the following is on its own row which looks incorrect:

For consistency, the data model for the POST /participants/{Type}/{ID} and POST /participants/{Type}/{ID}/{SubId} calls in Table 10 has been updated to include the optional ExtensionList element as well.

henrka · 2024-12-16T14:33:25Z

Table 7 should include the change on correlation IDs. This is a breaking change for all version 1.x, so all versions need to be bumped to 2.0 to capture the breaking change.

The same information update is then required for Tables 8, 15, 18, 22, 26, 29, 34, 37, and 41.

henrka

Review of the updated document, see also generic comments which are not directly related to the updated parts.

henrka · 2024-12-16T13:33:42Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -24,7 +24,7 @@ specified types of information.
 |**1.0**|2018-03-13|Initial version|
 |**1.1**|2020-05-19|1. This version contains a new option for a Payee FSP to request a commit notification from the Switch. The Switch should then send out the commit notification using the new request **PATCH /transfers/**_{ID}_. The option to use commit notification replaces the previous option of using the ”Optional Additional Clearing Check”. The section describing this has been replaced with the new section ”Commit Notification”. As the **transfers** resource has been updated with the new **PATCH** request, this resource has been updated to version 1.1. As part of adding the possibility to use a commit notification, the following changes has been made: <br>  a. PATCH has been added as an allowed HTTP Method in Section 3.2.2. b. The call flow for **PATCH** is described in Section 3.2.3.5. <br>c. Table 6 in Section 6.1.1 has been updated to include **PATCH** as a possible HTTP Method. <br>d. Section 6.7.1 contains the new version of the **transfers** resource. <br>e. Section 6.7.2.6 contains the process for using commit notifications <br>f. Section 6.7.3.3 describes the new **PATCH /transfers**/_{ID}_ request. <br><br>2. In addition to the changes mentioned above regarding the commit notification, the following non-API affecting changes has been made: <br>a. Updated Figure 6 as it contained a copy-paste error. <br>b. Added Section 6.1.2 to describe a comprehensive view of the current version for each resource. <br>c. Added a section for each resource to be able to see the resource version history. <br>d. Minor editorial fixes. <br><br>3. The descriptions for two of the HTTP Header fields in Table 1 have been updated to add more specificity and context<br>a. The description for the **FSPIOP-Destination** header field has been updated to indicate that it should be left empty if the destination is not known to the original sender, but in all other cases should be added by the original sender of a request. <br>b. The description for the **FSPIOP-URI** header field has been updated to be more specific. <br><br>4. The examples used in this document have been updated to use the correct interpretation of the Complex type ExtensionList which is defined in Table 84. This doesn’t imply any change as such. <br>a. Listing 5 has been updated in this regard. <br><br>5. The data model is updated to add an optional ExtensionList element to the **PartyIdInfo** complex type based on the Change Request: https://github.com/mojaloop/mojaloop-specification/issues/30. Following this, the data model as specified in Table 103 has been updated. For consistency, the data model for the **POST /participants/**_{Type}/{ID}_ and **POST /participants/**_{Type}/{ID}/{SubId}_ calls in Table 10 has been updated to include the optional ExtensionList element as well. <br><br>6. A new Section 6.5.2.2 is added to describe the process involved in the rejection of a quote. <br><br>7. A note is added to Section 6.7.4.1 to clarify the usage of ABORTED state in **PUT /transfers/**_{ID}_ callbacks.|
 |**1.1.1**|2021-09-22|This document version only adds information about optional HTTP headers regarding tracing support in [Table 2](#table-2), see _Distributed Tracing Support for OpenAPI Interoperability_ for more information. There are no changes in any resources as part of this version.|
-|**2.0**|2021-10-26|- The element named **initiatorType** has been removed from the complex type [**TransactionType**](#7418-transactiontype). This information is now supposed to be carried as part of the complex type [**Party**](#7411-party) instead, to be able to have more detail of the transaction by allowing to state the type of both the Payer and Payee. Section [5.3 Mapping of Use Cases to Transaction Types](#53-mapping-of-use-cases-to-transaction-types), has been updated to reflect this change. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/25.<br>- Two new types of a [**Party**](#7411-party) have been added to represent a government and a non-governmental organization in [**PartyType**](#759-partytype). This change is based on https://github.com/mojaloop/mojaloop-specification/issues/24.<br>- Two new possible [**PartyIdType**](#7325-partyidtype)s have been added in the enumeration [**PartyIdType**](#756-partyidtype) to support third party use cases. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/100.<br>-New endpoints and data structures have been added to support currency conversion. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/89. It has provided a [**/services**](#611-api-resource-services) resource to enable FSPs to obtain a list of participants who can provide conversion between two currencies. In addition, there are two further resources, [**/fxQuotes**](#612-api-resource-fxquotes) and [**fxTransfers**](#613-api-resource-fxtransfers), which provide functionality enabling FSPs to request and confirm a currency conversion, and request and confirm the execution of a previously agreed currency conversion respectively. These resources are the analogues for currency conversion of the **/quotes** and **/transfers** resources for payments.<br>- The definition of a correlation ID has been amended to support the use of ULIDs as well as UUIDs as globally unique identifiers.
+|**2.0**|2021-10-26|- The element named **initiatorType** has been removed from the complex type [**TransactionType**](#7418-transactiontype). This information is now supposed to be carried as part of the complex type [**Party**](#7411-party) instead, to be able to have more detail of the transaction by allowing to state the type of both the Payer and Payee. Section [5.3 Mapping of Use Cases to Transaction Types](#53-mapping-of-use-cases-to-transaction-types), has been updated to reflect this change. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/25.<br>- Two new types of a [**Party**](#7411-party) have been added to represent a government and a non-governmental organization in [**PartyType**](#759-partytype). This change is based on https://github.com/mojaloop/mojaloop-specification/issues/24.<br>- Two new possible [**PartyIdType**](#7325-partyidtype)s have been added in the enumeration [**PartyIdType**](#756-partyidtype) to support third party use cases. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/100.<br>-New endpoints and data structures have been added to support currency conversion. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/89. It has provided a [**/services**](#611-api-resource-services) resource to enable FSPs to obtain a list of participants who can provide conversion between two currencies. In addition, there are two further resources, [**/fxQuotes**](#612-api-resource-fxquotes) and [**fxTransfers**](#613-api-resource-fxtransfers), which provide functionality enabling FSPs to request and confirm a currency conversion, and request and confirm the execution of a previously agreed currency conversion respectively. These resources are the analogues for currency conversion of the **/quotes** and **/transfers** resources for payments.<br>- The definition of a correlation ID has been amended to support the use of ULIDs as well as UUIDs as globally unique identifiers.<br>- [A new element](https://github.com/mojaloop/mojaloop-specification/issues/130), **FSPIOP-Proxy**, has been added to the set of message header fields. It will allow a switch receiving a message to identify the proxy through which the message was received. The parameter is optional and does not form part of the set of header fields included in the non-repudiation signature.<br>- The _accept_ and _Content-Type_ parameters in the header have been [modified](#334-version-negotiation-between-client-and-server) to include explicit specification of the message format being used in the body of the message. This is aligned with the solution proposed in [Change Request 137](https://github.com/mojaloop/mojaloop-specification/issues/137).


Please add a link to #120 in the following: "- The definition of a correlation ID has been amended to support the use of ULIDs as well as UUIDs as globally unique identifiers."

henrka · 2024-12-16T13:36:21Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -24,7 +24,7 @@ specified types of information.
 |**1.0**|2018-03-13|Initial version|
 |**1.1**|2020-05-19|1. This version contains a new option for a Payee FSP to request a commit notification from the Switch. The Switch should then send out the commit notification using the new request **PATCH /transfers/**_{ID}_. The option to use commit notification replaces the previous option of using the ”Optional Additional Clearing Check”. The section describing this has been replaced with the new section ”Commit Notification”. As the **transfers** resource has been updated with the new **PATCH** request, this resource has been updated to version 1.1. As part of adding the possibility to use a commit notification, the following changes has been made: <br>  a. PATCH has been added as an allowed HTTP Method in Section 3.2.2. b. The call flow for **PATCH** is described in Section 3.2.3.5. <br>c. Table 6 in Section 6.1.1 has been updated to include **PATCH** as a possible HTTP Method. <br>d. Section 6.7.1 contains the new version of the **transfers** resource. <br>e. Section 6.7.2.6 contains the process for using commit notifications <br>f. Section 6.7.3.3 describes the new **PATCH /transfers**/_{ID}_ request. <br><br>2. In addition to the changes mentioned above regarding the commit notification, the following non-API affecting changes has been made: <br>a. Updated Figure 6 as it contained a copy-paste error. <br>b. Added Section 6.1.2 to describe a comprehensive view of the current version for each resource. <br>c. Added a section for each resource to be able to see the resource version history. <br>d. Minor editorial fixes. <br><br>3. The descriptions for two of the HTTP Header fields in Table 1 have been updated to add more specificity and context<br>a. The description for the **FSPIOP-Destination** header field has been updated to indicate that it should be left empty if the destination is not known to the original sender, but in all other cases should be added by the original sender of a request. <br>b. The description for the **FSPIOP-URI** header field has been updated to be more specific. <br><br>4. The examples used in this document have been updated to use the correct interpretation of the Complex type ExtensionList which is defined in Table 84. This doesn’t imply any change as such. <br>a. Listing 5 has been updated in this regard. <br><br>5. The data model is updated to add an optional ExtensionList element to the **PartyIdInfo** complex type based on the Change Request: https://github.com/mojaloop/mojaloop-specification/issues/30. Following this, the data model as specified in Table 103 has been updated. For consistency, the data model for the **POST /participants/**_{Type}/{ID}_ and **POST /participants/**_{Type}/{ID}/{SubId}_ calls in Table 10 has been updated to include the optional ExtensionList element as well. <br><br>6. A new Section 6.5.2.2 is added to describe the process involved in the rejection of a quote. <br><br>7. A note is added to Section 6.7.4.1 to clarify the usage of ABORTED state in **PUT /transfers/**_{ID}_ callbacks.|
 |**1.1.1**|2021-09-22|This document version only adds information about optional HTTP headers regarding tracing support in [Table 2](#table-2), see _Distributed Tracing Support for OpenAPI Interoperability_ for more information. There are no changes in any resources as part of this version.|
-|**2.0**|2021-10-26|- The element named **initiatorType** has been removed from the complex type [**TransactionType**](#7418-transactiontype). This information is now supposed to be carried as part of the complex type [**Party**](#7411-party) instead, to be able to have more detail of the transaction by allowing to state the type of both the Payer and Payee. Section [5.3 Mapping of Use Cases to Transaction Types](#53-mapping-of-use-cases-to-transaction-types), has been updated to reflect this change. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/25.<br>- Two new types of a [**Party**](#7411-party) have been added to represent a government and a non-governmental organization in [**PartyType**](#759-partytype). This change is based on https://github.com/mojaloop/mojaloop-specification/issues/24.<br>- Two new possible [**PartyIdType**](#7325-partyidtype)s have been added in the enumeration [**PartyIdType**](#756-partyidtype) to support third party use cases. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/100.<br>-New endpoints and data structures have been added to support currency conversion. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/89. It has provided a [**/services**](#611-api-resource-services) resource to enable FSPs to obtain a list of participants who can provide conversion between two currencies. In addition, there are two further resources, [**/fxQuotes**](#612-api-resource-fxquotes) and [**fxTransfers**](#613-api-resource-fxtransfers), which provide functionality enabling FSPs to request and confirm a currency conversion, and request and confirm the execution of a previously agreed currency conversion respectively. These resources are the analogues for currency conversion of the **/quotes** and **/transfers** resources for payments.<br>- The definition of a correlation ID has been amended to support the use of ULIDs as well as UUIDs as globally unique identifiers.
+|**2.0**|2021-10-26|- The element named **initiatorType** has been removed from the complex type [**TransactionType**](#7418-transactiontype). This information is now supposed to be carried as part of the complex type [**Party**](#7411-party) instead, to be able to have more detail of the transaction by allowing to state the type of both the Payer and Payee. Section [5.3 Mapping of Use Cases to Transaction Types](#53-mapping-of-use-cases-to-transaction-types), has been updated to reflect this change. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/25.<br>- Two new types of a [**Party**](#7411-party) have been added to represent a government and a non-governmental organization in [**PartyType**](#759-partytype). This change is based on https://github.com/mojaloop/mojaloop-specification/issues/24.<br>- Two new possible [**PartyIdType**](#7325-partyidtype)s have been added in the enumeration [**PartyIdType**](#756-partyidtype) to support third party use cases. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/100.<br>-New endpoints and data structures have been added to support currency conversion. This change is based on https://github.com/mojaloop/mojaloop-specification/issues/89. It has provided a [**/services**](#611-api-resource-services) resource to enable FSPs to obtain a list of participants who can provide conversion between two currencies. In addition, there are two further resources, [**/fxQuotes**](#612-api-resource-fxquotes) and [**fxTransfers**](#613-api-resource-fxtransfers), which provide functionality enabling FSPs to request and confirm a currency conversion, and request and confirm the execution of a previously agreed currency conversion respectively. These resources are the analogues for currency conversion of the **/quotes** and **/transfers** resources for payments.<br>- The definition of a correlation ID has been amended to support the use of ULIDs as well as UUIDs as globally unique identifiers.<br>- [A new element](https://github.com/mojaloop/mojaloop-specification/issues/130), **FSPIOP-Proxy**, has been added to the set of message header fields. It will allow a switch receiving a message to identify the proxy through which the message was received. The parameter is optional and does not form part of the set of header fields included in the non-repudiation signature.<br>- The _accept_ and _Content-Type_ parameters in the header have been [modified](#334-version-negotiation-between-client-and-server) to include explicit specification of the message format being used in the body of the message. This is aligned with the solution proposed in [Change Request 137](https://github.com/mojaloop/mojaloop-specification/issues/137).


Strange to have the link in "A new element" in the following: "- A new element, FSPIOP-Proxy, has been added to the set of message header fields." Suggesting putting the link at the end to keep same structure as other bullets.

henrka · 2024-12-16T13:44:17Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -445,7 +446,7 @@ See below for an example of a simplified HTTP request which only includes an **A

 ```
 POST /service HTTP/1.1
-Accept: application/vnd.interoperability.{resource}+json;version=1,
+Accept: application/vnd.interoperability.{messagetype}.{resource}+json;version=1,


Hmm I think the old structure was supposed to be kept as is for FSPIOP? @PaulGregoryBaker to confirm..

henrka · 2024-12-16T13:44:23Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -459,7 +460,7 @@ Regarding the example in [Listing 3](#listing-3):

 - The **_POST /service_** should be changed to any HTTP method and related service or resource that is supported by the API (see [Table 6](#table-6)).
 - The **Accept** header field is used to indicate the API resource version the client would like to use. If several versions are supported by the client, more than one version can be requested separated by a comma (**,**) as in the example above.
-  - The application type is always **application/vnd.interoperability.**_{resource}_, where _{resource}_ is the actual resource (for example, **participants** or **quotes**).
+  - The application type is always **application/vnd.interoperability**._{messagetype}_._{resource}_, where {messagetype} is the format used for the message (for example, **fspiop** or **iso20022**), and {resource} is the actual resource (for example, **participants** or **quotes**).


Hmm I think the old structure was supposed to be kept as is for FSPIOP? @PaulGregoryBaker to confirm..

henrka · 2024-12-16T13:44:39Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -471,7 +472,7 @@ If the server supports the API resource version requested by the client in the A
 ###### Listing 4

 ```
-Content-Type: application/vnd.interoperability.resource+json;version=1.0
+Content-Type: application/vnd.interoperability.messagetype.resource+json;version=1.0


Hmm I think the old structure was supposed to be kept as is for FSPIOP? @PaulGregoryBaker to confirm..

henrka · 2024-12-16T14:53:36Z

fspiop-api/documents/API Definition v2.0-alpha.md

@@ -3133,27 +3566,29 @@ Two examples of the **Date** type appear below:
 **1982-05-23**<br>
 **1987-08-05**

-#### 7.2.16 UUID
+#### 7.2.16 Uniqueidentifier


Uniqueidentifier -> UniqueIdentifier (capital I in Identifier)

henrka · 2024-12-16T15:00:07Z

fspiop-api/documents/API Definition v2.0-alpha.md


-[Table 56](#table-56) contains the data model for the element **ErrorCode**.
+[Table ]69(#table-69) contains the data model for the element **ErrorCode**.


[Table ]69(#table-69)

Should be Table 69 (misplaced "]")

henrka · 2024-12-16T15:01:52Z

fspiop-api/documents/API Definition v2.0-alpha.md

+
+| **Name** | **Cardinality** | **Format** | **Description** |
+| --- | --- | --- | --- |
+| **chargeType** | 1 | String(1..32) | A descripition of the charge that is being levied |


descripition -> description

henrka · 2024-12-16T15:02:52Z

fspiop-api/documents/API Definition v2.0-alpha.md

+| **Name** | **Cardinality** | **Format** | **Description** |
+| --- | --- | --- | --- |
+| **currency** | 1 | Currency | The currency of the amount, as described in Section 7.3.9 above.
+ |


This should end the row above instead of being on its own line.

henrka · 2024-12-16T15:03:25Z

fspiop-api/documents/API Definition v2.0-alpha.md

+
+| **Name** | **Cardinality** | **Format** | **Description** |
+| --- | --- | --- | --- |
+| **currency** | 1 | Currency | The currency of the amount, as described in Section 7.3.9 above.


Remove "above", as this makes it hard to maintain the document.

Moving the FX changes PR from documentation repo to the ML specificat…

14108c8

…ion repo on Behalf of Michael Richards for the FSPIOP SIG

elnyry-sam-k requested review from millerabel and MichaelJBRichards as code owners April 25, 2024 10:53

elnyry-sam-k requested a review from henrka April 25, 2024 10:53

henrka reviewed May 2, 2024

View reviewed changes

MichaelJBRichards added 2 commits June 28, 2024 16:14

Update API Definition v2.0-alpha.md

a9df72d

Addressing PR comments

Update API Definition v2.0-alpha.md

947ff86

Responses to Henrik's comments

henrka reviewed Jul 15, 2024

View reviewed changes

Update API Definition v2.0-alpha.md

6918644

Responses to Henrik's review 20240715

henrka reviewed Jul 18, 2024

View reviewed changes

fspiop-api/documents/API Definition v2.0-alpha.md Outdated Show resolved Hide resolved

MichaelJBRichards and others added 5 commits July 19, 2024 12:05

Update API Definition v2.0-alpha.md

03b8d2e

Responding to comments from Henrik Karlsson.

Update API Definition v2.0-alpha.md

f69cbc1

Added links to specification sections from introduction

Update API Definition v2.0-alpha.md

a68b1be

Changes to support ULIDs as unique identifiers as well as UUIDs

Merge branch 'master' into feat/fx-changes

968ff12

Update API Definition v2.0-alpha.md

52316fb

Add new header parameter and changes to accept and content-type parameter syntax.

henrka reviewed Dec 16, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: moving the fx changes pr from documentation repo here #129

feat: moving the fx changes pr from documentation repo here #129

elnyry-sam-k commented Apr 25, 2024

henrka left a comment

henrka Jul 15, 2024

henrka left a comment

henrka commented Dec 16, 2024

henrka commented Dec 16, 2024

henrka commented Dec 16, 2024

henrka left a comment

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024

henrka Dec 16, 2024


		[Table 56](#table-56) contains the data model for the element ErrorCode.
		[Table ]69(#table-69) contains the data model for the element ErrorCode.

feat: moving the fx changes pr from documentation repo here #129

Are you sure you want to change the base?

feat: moving the fx changes pr from documentation repo here #129

Conversation

elnyry-sam-k commented Apr 25, 2024

henrka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

henrka left a comment

Choose a reason for hiding this comment

henrka commented Dec 16, 2024

henrka commented Dec 16, 2024

henrka commented Dec 16, 2024

henrka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment