Change Request: Extend PartyIdType for Third Party API
lewisdaly 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 | Lewis Daly, Crosslake |
| Change Request Status | In review ☒ / Approved ☐ / Rejected ☐ |
| Approved/Rejected Date |
1.2 Document Version Information
| Version | Date | Author | Change Description |
|---|---|---|---|
| 1.0 | 2021-10-12 | Lewis Daly | Initial version of change request. |
2. Problem Description
___2.1 Background
The proposed Third Party API reuses a number of existing data models and API resources as the
FSPIOP API. In particular are the resources /participants and /parties, which the API
proposes to use to (1) register and lookup the authoritative source of a Consent object with
the Account Lookup Service, and (2) register and lookup an account identifier issued by an FSP
to a PISP.
See the following links for examples of how these resources are used in the Third Party API:
In order to use these resources in the Third Party API, the PartyIdType enumeration must be
extended to include the allowed values CONSENT and THIRD_PARTY_LINK.
2.2 Current Behaviour
The existing FSPIOP API does not allow for the a PartyIdType of CONSENT or THIRD_PARTY_LINK in the
/participants or /parties resources.
Requests such as GET /parties/CONSENT/<ID> or POST /participants/THIRD_PARTY_LINK/<ID> are considered
invalid.
2.3 Requested Behaviour
The PartyIdType
enum should be extended to include the following values:
| Name | Description |
|---|---|
| CONSENT | A Consent represents an agreement between a PISP, a Customer and a DFSP which allows the PISP permission to perform actions on behalf of the customer. A Consent has an authoritative source: either the DFSP who issued the Consent, or an Auth Service which administers the Consent. |
| THIRD_PARTY_LINK | A Third Party Link represents an agreement between a PISP, a DFSP, and a specific Customer's account at the DFSP. The content of the link is created by the DFSP at the time when it gives permission to the PISP for specific access to a given account. |
The following are 4 example HTTP requests of how the extended PartyIdType fields may be used:
Example 1 - Association of a THIRD_PARTY_LINK identifier to a PISP
POST /participants/THIRD_PARTY_LINK/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Content-Length: 50
Content-Type: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: dfspa
FSPIOP-Destination: Switch
{
"fspId": "pispa"
}
Example 2 - Lookup of a THIRD_PARTY_LINK identifier
GET /participants/THIRD_PARTY_LINK/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:13:24 GMT
FSPIOP-Source: dfspb
FSPIOP-Destination: Switch
Example 3 - Association of a CONSENT identifier to an Auth Service
POST /participants/CONSENT/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Content-Length: 50
Content-Type: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: CentralAuthService
FSPIOP-Destination: Switch
{
"fspId": "CentralAuthService"
}
Example 4 - Lookup of a consent's owner based on a consentId
GET /participants/CONSENT/123456789 HTTP/1.1
Accept: application/vnd.interoperability.participants+json;version=1.1
Date: Tue 12 Oct 2021 10:12:24 GMT
FSPIOP-Source: pispa
3. Proposed Solution Options
___Alternatively to the solution described in [#requested-behaviour](Requested Behaviour), the Third Party API
could maintain it's own version to the PartyIdType field, with the extended fields included.
Sorry for the unassign and reassign, accidentally clicked wrong button :)
I'm fine with adding the required types so that the enum can be reused.
Thanks @ehenrka . What's the next step here? Perhaps we can discuss at the next FSPIOP SIG meeting?
What's your view on versioning here? I know we have version numbers for the resources, so would this change bump the minor versions of the participants and parties resources?
Yes, I'll bring it up on the next FSPIOP SIG meeting (October 19th) to request feedback. You are more than welcome to join the meeting if you want to, but I guess the scheduled time (16:00 CET) is not that good for you.. I hope that @mjbrichards and myself can answer most of the questions that might pop up.
It can be a bit sensitive to update enums, as implementers might expect certain elements. In Section 3.3.3 (Major API Resource Versions), we have decided that a changed data type means a major version, and Section 7.2.2 (Enum) says that other values than the ones defined in the list are not allowed. In hindsight, we should have defined in Section 3.3 what an addition of a value in an enum means a minor or a major version, as this currently is a bit of a grey-zone. We can discuss this in the CCB as well, but any change of the versioning strategy should then be in the next major version.
To be on the safe side for the additions to the PartyIdType enum, I would recommend a new major version, as we are anyway planning to release a new version 2.0 of the FSPIOP API. A new version 2.0 is already required by for example #25. The update of the possible PartyIdTypes will then affect many of the resources in FSPIOP API, as it is used inside a Party, which is used in many resources.
But as long as we have agreed to add the two new values as part of this change request, the Third Party API should not have to wait until the FSPIOP API is on version 2 of the participants and parties resources. FSPIOP API will then start to use version 2 of these resources when we have completed that release for FSPIOP API.
Thanks @ehenrka. I should be able to make that call, so please extend the invite.
I agree that this looks like it needs to be included in the next major version of the FSPIOP API, but good to hear that the Third Party API won't be blocked by this release.
@lewisdaly, please see #101 for the two new added PartyIdTypes in v2.0.
Please note that the /parties resource will probably be updated once more based on #89 to incorporate the possible receiving currencies for a Party, so this is probably not the final version just yet. Maybe @mjbrichards can go ahead and create a change request on FSPIOP API just for that change, so that we can get a final 2.0 version of the /parties resource?