feat: moving the fx changes pr from documentation repo here

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).
 
 ## 2. Introduction
 
@@ -221,6 +221,7 @@ The API supports a maximum size of 65536 bytes (64 Kilobytes) in the HTTP header
 |**FSPIOP- Signature**||0..1|The **FSPIOP-Signature** header field is a non-HTTP standard field used by the API for applying an end-to-end request signature.<br>For more information, see API Signature.</br>|
 |**FSPIOP-URI**|**/parties/msisdn/123456789**|0..1|The **FSPIOP-URI** header field is a non- HTTP standard field used by the API for signature verification, should contain the service URI. Required if signature verification is used, for more information see _API Signature_. <br> In the context of the Mojaloop FSPIOP API, the value for FSPIOP-URI starts with the **_service_** in the URI value. For example, if a URL is http://stg-simulator.moja.live/payerfsp/participants/MSISDN/123456789, then the FSPIOP-URI value is “/participants/MSISDN/123456789”.|
 |**FSPIOP- HTTP- Method**|**GET**|0..1|The **FSPIOP-HTTP-Method** header field is a non-HTTP standard field used by the API for signature verification, should contain the service HTTP method. Required if signature verification is used, for more information see API Signature.|
+|**FSPIOP-Proxy**|**Proxy1**|0..1|The **FSPIOP-Proxy** header field is a non-HTTP standard field used by the API for HTTP header-based routing of requests and responses to the destination. If the message is being forwarded by a proxy, the field must be set by the proxy, so that any entities between the client and the server, as well as the server itself, can recognise that the message has been forwarded by a proxy, and which proxy it was which forwarded it. The server can therefore take action accordingly. If the message is being sent by a DFSP, an FXP or any other type of entity, then this parameter should be omitted or, if not omitted, left blank.|
 
 **Table 1 -- HTTP request header fields that must be supported**
 
@@ -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,
 application/vnd.interoperability.{resource}+json
 
 {
@@ -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**).
   - The only data exchange format currently supported is **json**.
   - If a client can use any minor version of a major version, only the major version should be sent; for example, **version=1** or **version=2**.
   - If a client would like to use a specific minor version, this should be indicated by using the specific _major.minor_ version; for example, **version=1.2** or **version=2.8**. The use of a specific _major.minor_ version in the request should generally be avoided, as minor versions should be backwards-compatible.
@@ -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
 ```
 
 **Listing 4 -- Content-Type HTTP header field example**
@@ -505,6 +506,11 @@ Along with HTTP status 406, the supported versions should be listed as part of t
 
 **Listing 5 -- Example error message when server does not support the requested version**
 
+
+#### 3.3.4.4 Message type determination
+
+The use of the _accept_ and _content-type_ parameters may lead to ambiguities. These should be resolved in the following way. If no message type is given in the _accept_ and _content-type_ parameters, then a recipient of the message should assume that the message format being used is _fspiop_. If one of the _accept_ and _content-type_ parameters specifies a message format and the other does not, then a recipient of the message should assume that the message format being used is the one explicitly specified. If the _accept_ parameter and the _content-type_ parameter specify different message formats, then a recipient of the message should report an error.
+
 <sup>1</sup>  [http://www.ics.uci.edu/\~fielding/pubs/dissertation/rest\_arch\_style.htm](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) -- Representational State Transfer (REST)
 
 <sup>2</sup>  [https://tools.ietf.org/html/rfc4122](https://tools.ietf.org/html/rfc4122) -- A Universally Unique IDentifier (UUID) URN Namespace