Change Request: Clarify usage of "ABORTED" transfer state in a PUT /transfers/{ID} call
elnyry-sam-k opened this issue · comments
Open API for FSP Interoperability - Change Request
Table of Contents
1. Preface
___This section contains basic information regarding the change request.
1.1 Change Request Information
| Requested By | Sam Kummary, ModusBox |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date | |
1.2 Document Version Information
| Version | Date | Author | Change Description |
|---|---|---|---|
| 1.0 | 2020-02-11 | Sam Kummary | Initial version proposed and discussed with the CCB |
2. Problem Description
___2.1 Background
The TransferState enumeration defined in Section 7.5.13 of the API Definition v1.0 has these four values: RECEIVED, RESERVED, COMMITTED, ABORTED (Section 6.7.5 gives the possible states of a transfer). These states are fine to indicate the status of a transfer on a single FSP (or ledger), however the current issue is regarding the usage of the "ABORTED" state in a PUT /transfers/{ID} call described in Section 6.7.3.1 (corresponding to an initial POST /transfers call).
2.2 Current Behaviour
As part of fulfilling a prepared transfer (done via POST /transfers) using PUT /transfers/{ID} endpoint, it is possible to send the 'transferState' as ABORTED because its a valid enumeration value. Its possible for FSPs to interpret this as a valid option to abort transfers instead of using the PUT /transfers/{ID}/error endpoint.
The current Switch implementation caters for both of these options (ABORTED transferState sent in a PUT /transfers call or using a PUT /transfers/{ID}/error). The former doesn't have scope to add any additional information regarding the error or abort request, whereas the call on /error endpoint does have a field that can be used (along with error code).
After discussion with the CCB, the understanding was that the error endpoint (/transfers/{ID}/error) needs to be used by an FSP in case a transfer needs to be aborted and not use the PUT /transfers/{ID} call with an "ABORTED" value in the transferState field.
Example:
- A Payer FSP makes a POST /transfers call to make a transfer request
{
"transferId": "b8114fc7-56b4-4929-8943-5877c73dfcec",
"payerFsp": "payerfsp",
"payeeFsp": "payeefsp",
"amount": {
"amount": "1.11",
"currency": "USD"
},
"expiration": "2020-02-11T14:18:27.921Z",
"ilpPacket": "AQAAAAAAAADIEHByaXZhdGUucGF5ZWVmc3CCAiB7InRyYW5zYWN0aW9uSWQiOiIyZGY3NzRlMi1mMWRiLTRmZjctYTQ5NS0yZGRkMzdhZjdjMmMiLCJxdW90ZUlkIjoiMDNhNjA1NTAtNmYyZi00NTU2LThlMDQtMDcwM2UzOWI4N2ZmIiwicGF5ZWUiOnsicGFydHlJZEluZm8iOnsicGFydHlJZFR5cGUiOiJNU0lTRE4iLCJwYXJ0eUlkZW50aWZpZXIiOiIyNzcxMzgwMzkxMyIsImZzcElkIjoicGF5ZWVmc3AifSwicGVyc29uYWxJbmZvIjp7ImNvbXBsZXhOYW1lIjp7fX19LCJwYXllciI6eyJwYXJ0eUlkSW5mbyI6eyJwYXJ0eUlkVHlwZSI6Ik1TSVNETiIsInBhcnR5SWRlbnRpZmllciI6IjI3NzEzODAzOTExIiwiZnNwSWQiOiJwYXllcmZzcCJ9LCJwZXJzb25hbEluZm8iOnsiY29tcGxleE5hbWUiOnt9fX0sImFtb3VudCI6eyJjdXJyZW5jeSI6IlVTRCIsImFtb3VudCI6IjIwMCJ9LCJ0cmFuc2FjdGlvblR5cGUiOnsic2NlbmFyaW8iOiJERVBPU0lUIiwic3ViU2NlbmFyaW8iOiJERVBPU0lUIiwiaW5pdGlhdG9yIjoiUEFZRVIiLCJpbml0aWF0b3JUeXBlIjoiQ09OU1VNRVIiLCJyZWZ1bmRJbmZvIjp7fX19",
"condition": "HOr22-H3AfTDHrSkPjJtVPRdKouuMkDXTR4ejlQa8Ks"
}
- Following a POST /transfers call by the Payer FSP, a Payee FSP responds with a PUT /transfers/{ID} with an ABORTED transferState (other fields are optional)
Call on:
PUT /transfers/{b8114fc7-56b4-4929-8943-5877c73dfcec}
{
"completedTimestamp": "2020-02-11T14:08:28.417Z",
"transferState": "ABORTED"
}
- Since this (ABORTED) is a valid state, the Switch is having to process it and consider the transfer as aborted. With the change suggested, a PUT /transfers/{ID} call that looks like the above will fail Schema validation or will receive an error callback
2.3 Requested Behaviour
There is no request for a change in the behavior of the API as such, but to add more description to indicate the behaviour described above explicitly - to not use ABORTED state in PUT /transfers/{ID} calls and only use a PUT call on the error endpoint if a transfer needs to be aborted.
This will have significant implication to the Switch implementation on the OSS side which will help simplify things.
3. Proposed Solution Options
___Summarized in Section 2.3 above. Additional description offering clarity on this would be helpful for both FSPs and Switch/Hub implementers.
Yes, an FSP should never send ABORTED in PUT /transfers as a callback for POST /transfers, as this is a request to create a transfer. The error callback PUT /transfers/<ID>/error must be sent to indicate that the request to create the transfer has failed in the FSP.
Please note that it should however be possible that an FSP could reply with ABORTED in PUT /transfers as a callback to GET /transfers, if the Switch (or another FSP) would like to get information regarding a previously-created transfer.
It sounds good to me to directly respond with a HTTP 400 (https://tools.ietf.org/html/rfc7231#section-6.5.1) indicating schema validation error if an FSP would send ABORTED in PUT /transfers as a callback for POST /transfers. (Another alternative would be to add 409 (conflict) (https://tools.ietf.org/html/rfc7231#section-6.5.8) to Section 3.2.4, but I think 400 is good enough).
Please note that it should however be possible that an FSP could reply with ABORTED in PUT /transfers as a callback to GET /transfers, if the Switch (or another FSP) would like to get information regarding a previously-created transfer.
Definitely
Thanks for the comment Henrik.
Regarding responding to a PUT /transfers call with a 400, the issue is that since callbacks to both a GET /transfers/{ID} call and a POST /transfers look alike - PUT /transfers/{ID}, I'm not sure if doing this at the Schema Validation level will be possible, as additional context is needed. However, if we can make it work at Schema validation level, it will be efficient for everyone involved. If we need to send a 400 here, we need to additional processing at the API layer in addition to schema validation. Given this constraint, I'm thinking an error callback is more appropriate.. What do you think?
Yes, you are absolutely correct that there might be a problem in the implementation to be able to discern between the two to keep the processing asynchronous. The problem with using an error callback is that it would be a new PUT request back to the Payee FSP, which it does not expect (and should not).
The alternative if the implementation in the switch needs additional context by looking up if it was a POST- or a GET /transfers is to only describe in the API Definition document how it should be done. If an FSP should anyway use ABORTED in PUT /transfers as a callback for POST /transfers, then manually inform them about the error. This erroneous behaviour should be discovered during testing. This is how we have handled similar issues before.
Ok, thanks Henrik. Adding the description in the API Definition about the ABORTED state's usage should suffice then.
Just some minor formatting/styling comments:
- The note itself should be properly formatted. There is for example no indentation of the text as in other notes in the document. Please see for example the note in Section 6.8.6. The easiest should be to just copy an existing note in the document and replace the text in the existing note.
- Elements in the API should not be surrounded by single apostrophes ('). The following is an example excerpt from the text where the apostrophes should be removed:
..., the state ‘ABORTED’ is not a valid value as ‘transferState’ ...
- When a table is referenced, only the table number should be included, not the table description. For example, only "Table 1" should be used instead of "Table 1 - Some table description".
Table 31 – PUT /transfers/ data model
Thanks for the feedback, Henrik.
Here is the updated draft with updates to the "note" section under /transfers:
API Definition_v1.1-draft_Updated-2020-04-13.docx
Closed with v1.1 of the Spec