search

mojaloop / mojaloop-specification

This repo contains the specification document set of the Open API for FSP Interoperability
https://docs.mojaloop.io/api
Other
20 stars 40 forks source link

Change Request: Extend PartyIdType for Third Party API #100

Open lewisdaly opened 3 years ago

lewisdaly commented 3 years ago

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.

henrka commented 3 years ago

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.

lewisdaly commented 3 years ago

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?

henrka commented 3 years ago

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.

lewisdaly commented 3 years ago

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.

henrka commented 3 years ago

@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?