feat: add thirdparty api specification and supporting docs #90

lewisdaly · 2021-07-20T07:51:10Z

Closes #70

This PR adds the Third Party API specification, along with supporting documentation, sequences etc.

TODOS:

Update the OpenAPI files to the latest version
Convert Michael's document to a markdown version
update data model for POST /thirdpartyRequests/authorizations based on @ehenrka feedback: Draft API Definition for the PISP / third party API #70 (comment)

elnyry-sam-k · 2021-07-20T08:22:52Z

Thanks for this @lewisdaly - having the readme docs, API definition doc and the yaml files (openapi 3.x) is all we need!

lewisdaly · 2021-07-20T08:28:02Z

Great! Thanks @elnyry-sam-k .

fix: readme table fix: unbound arrays feat: update _sync_docs to reflect new master docs feat: update svgs feat: copy across puml sources from pisp repo feat: copy across puml sources from pisp repo chore: refactor assets dir chore: refactor assets dir chore: rerender svgs feat: update puml styling feat: rerender puml chore: clean up pumls chore: clean up pumls chore: clean up pumls chore: clean up pumls feat: tidy up todos from tx patterns docs chore: cleaning up heading indents chore: cleaning up heading indents chore: cleaning up heading indents chore: cleaning up heading indents chore: add toc chore: add toc feat: clean up error codes chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting chore: clean api formatting feat: clean up error scenarios for linking feat: clean up error scenarios for linking feat: clean up error scenarios for linking feat: clean up error scenarios for linking feat: clean up error scenarios for transfer

lewisdaly · 2021-10-05T02:34:20Z

@ehenrka it's ready to go again for another review.

I think I addressed most of your comments, and I marked those I was sure I addressed as "resolved".

I still am yet to update the swagger files, but I'll wait until you are happy with the .md and puml docs

henrka · 2021-10-11T07:02:51Z

I'm working on reviewing the updates now, sorry for the delay as I had to prioritize other tasks last week.

A generic comment is that the formatting is more consistent, but it lacks the variables formatting (from the new section 1.1 Conventions Used in This Document) with italics everywhere that I have seen so far.

As an example:

Callback and data model information for GET /accounts/{ID}:

Callback - PUT /accounts/{ID}

Error Callback - PUT /accounts/{ID}/error

Data Model – Empty body

Should be:

Callback and data model information for GET /accounts/{ID}:

Callback - PUT /accounts/{ID}
Error Callback - PUT /accounts/{ID}/error
Data Model – Empty body

Should be fairly simple to just do a search and replace of instance of "/{ID}" to "/_{ID}_"..

lewisdaly · 2021-10-11T07:04:09Z

Callback and data model information for GET /accounts/{ID}:

Ah I see - I missed that nuance

henrka

Here is my updated review. Please note that I have not done a thorough review as last time, more to check my old comments and some quick look at the formatting.

henrka · 2021-10-11T06:40:31Z

thirdparty-api/README.md

+
+| **Term** | **Alternative and Related Terms** | **Definition** | **Source** |
+| --- | --- | --- | --- |
+| **Payment Initiation Service Provider** | PISP, 3rd Party Payment Initiator (3PPI) | "Regulated entities like retail banks or third parties, that allow customers to make payments without accessing bank accounts or cards | [PSD2](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32015L2366&qid=1633311418487) |


"Regulated entities ...

Remove the "

henrka · 2021-10-11T06:42:41Z

thirdparty-api/README.md

+| **Term** | **Alternative and Related Terms** | **Definition** | **Source** |
+| --- | --- | --- | --- |
+| **Payment Initiation Service Provider** | PISP, 3rd Party Payment Initiator (3PPI) | "Regulated entities like retail banks or third parties, that allow customers to make payments without accessing bank accounts or cards | [PSD2](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32015L2366&qid=1633311418487) |
+| **FSP** | Provider, Financial Service Provider (FSP), Payment Service Provider, Digital Financial Services Provider (DFSP) | The entity that provides a digital financial service to an end user (either a consumer, a business, or a government.) In a closed-loop payment system, the Payment System Operator is also the provider. In an open- loop payment system, the providers are the banks or non-banks which participate in that system. | [ITU-T](https://www.itu.int/dms_pub/itu-t/opb/tut/T-TUT-ECOPO-2018-PDF-E.pdf) |


In an open- loop payment system ...

"open- loop" should be "open-loop"

henrka · 2021-10-11T06:49:18Z

thirdparty-api/data-models.md

+#### 3.1.1 `/accounts`
+
+The `/accounts` resource is used to request information from a DFSP relating to the accounts 
+it holds for a given identifier. The identifier is given to the PISP by the user, and the 


But this is the first time "identifier" is used. How should I as a reader know that I have to read section 3.1.1.1.1 to know what an identifier is?

henrka · 2021-10-11T06:53:52Z

thirdparty-api/data-models.md

+
+##### 3.1.1.1 Requests
+
+This section describes the services that a PISP can request on the /accounts resource.


Still not formatted correctly. Section 1.1 says:

Type of Information Convention Example

Elements of the API, such as resources Boldface /authorization

Variables Italics with in angle brackets {ID}

...

henrka · 2021-10-11T07:07:54Z

thirdparty-api/data-models.md

+
+| Name | Cardinality | Type | Description |
+| --- | --- | --- | --- |
+| accountList | 1 | AccountList | Information about the accounts that the DFSP associates with the identifier sent by the PISP. |


Yes, it will require more work in each update to keep links correct, but it also makes the document a lot easier to read. We have it in the API Definition at least for most of the links, though some links have probably slipped away. For the updates I have done recently, I'm using a script to incremenent each subsequent section/figure/table/listing number if I want to add a section/figure/table/listing in the middle of the document.

But I'm leaving the decision up to you, it is not like the document can't be used without the links, just a lot more reader-friendly.

henrka · 2021-10-11T07:54:00Z

thirdparty-api/transaction-patterns-linking.md

+the PISP.
+
+
+1. _let `consentId` be the value of the `body.consentId` in the **POST /consents** request_


let ...

let ...

Use uppercase "L" in "Let ..."

henrka · 2021-10-11T07:55:49Z

thirdparty-api/transaction-patterns-transfer.md

+
+| Reference | Description | Version | Link |
+| --- | --- | --- | --- |
+| Ref. 1 | Open API for FSP Interoperability | `1.1` | [API Definition v1.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md)|


The reference to the FSPIOP API Definition is currently not used in this document. But, I think it would be good if you could point to Section 3 in the FSPIOP API Definition, where the architecture of the API is detailed, as I think the same the same basic architecture is used for the Third Party API? Maybe as part of the introduction.

henrka · 2021-10-11T07:59:11Z

thirdparty-api/transaction-patterns-transfer.md

+
+## <a id='DerivingtheChallenge'></a>6.1 Deriving the Challenge
+
+1. let `quote` be the value of the response body from the **PUT /quotes/{ID}** call


let ...

let ...

let ...

Please use "Let" instead of "let".
Additionally, in Section 3.6.1 in the linking document, the steps was in italics. Please use similar formatting.

henrka · 2021-10-11T07:59:58Z

thirdparty-api/transaction-patterns-transfer.md

+
+## <a id='badpayeelookup'></a> 5.1 Unsuccessful Payee Lookup
+
+<!-- TODO: update these sequences with updated error codes -->


Either fix todo or remove it before release

henrka · 2021-10-11T08:07:06Z

thirdparty-api/transaction-patterns-transfer.md

+    - _privatekey_ (stored by the PISP when creating the credential), as a base64 encoded utf-8 string
+    - SHA256() is a one way hash function, as defined in [RFC6234](https://datatracker.ietf.org/doc/html/rfc6234)
+    - sign(data, key) is a signature function that takes some data and a private key to produce a signature
+2. let _challengeHash_ be the result of applying the SHA256() function over the _challenge_


let ...

let ...

Please use "Let" instead of "let".
Additionally, in Section 3.6.1 in the linking document, the steps was in italics (but it is not used in 6.1). Please use similar formatting.

lewisdaly · 2021-10-12T02:34:42Z

Thanks @ehenrka. I found I can't comment on some of the comments you made, so I'll include some replies below:

Thanks! Can we describe this somewhere in the document so that it more clear?

Yep, Credential is defined in section 3.2.1.10

Should be fairly simple to just do a search and replace of instance of "/{ID}" to "/{ID}"..
I think I've got them all this time.

No, it should preferably not send a PUT as it is used for callbacks today. Something along the following is how I would suggest it to be:...

I'd rather we just suggest to the PISP to call the GET /services resource once a day and cache the results. That seems much simpler than defining and implementing such a subscription mechanism.

henrka · 2021-10-12T07:00:00Z

I'd rather we just suggest to the PISP to call the GET /services resource once a day and cache the results. That seems much simpler than defining and implementing such a subscription mechanism.

That is perfectly fine by me.

elnyry-sam-k · 2021-11-05T14:39:15Z

@lewisdaly - as we discussed in the CCB meeting, is this now ready to go? (can you please update the branch etc).. @ehenrka any further comments?

henrka · 2021-11-09T07:03:34Z

I'm happy with the updates from @lewisdaly.

lewisdaly · 2021-11-09T07:16:32Z

Great! Thanks @ehenrka. @elnyry-sam-k I guess we are good to merge in then...

elnyry-sam-k · 2021-11-09T12:37:49Z

Thanks @lewisdaly , please go ahead!

lewisdaly added 2 commits July 20, 2021 16:18

chore: add basic readme directory for 3rd party api

db97225

feat: add initial thirdparty api docs for review

982d259

lewisdaly self-assigned this Jul 20, 2021

lewisdaly requested a review from MichaelJBRichards July 20, 2021 07:57

lewisdaly and others added 13 commits August 6, 2021 11:03

feat: start working on .md translation, preview how it looks in github

6389e9e

feat: converting more resources to md

c3b3c25

feat: magic regex

36e7045

feat: converting more resources to md

cf1cece

feat: converting more resources to md

1a808ca

feat: add models

5613806

feat: add models

f372a69

feat: finish updating tables

ac45cc5

fix: link to ref1

2fca462

fix: links to exteral refs

2a4775b

feat: finish first pass at .md format

d392d70

feat: update data model for `POST /thirdpartyRequests/authorizations

830b9ae

feat: update data model for `POST /thirdpartyRequests/verifications

a222604

lewisdaly mentioned this pull request Aug 11, 2021

feat(thirdparty): update payloads for authorizations and verifications resources mojaloop/api-snippets#102

Merged

lewisdaly added 10 commits September 23, 2021 13:06

feat: update PUT /tpr/authorizations/{ID} data model

6c6b11f

feat: remove redundant reference to fspiop api

7d774c5

feat: re-sync external docs

0cc7c28

feat: add terms

ca68abd

feat: clean up data models

95b20f5

chore: minor api updates

3fafb8b

chore: clean and tidy data models

be2cdfb

feat: tidy up the credential models

b1dcf5e

fix: remove unused data models, fix up references

fd6c410

chore: update dfsp and pisp swagger docs

8fb6ff6

lewisdaly added 5 commits October 4, 2021 16:20

feat: work on TOC

da30a39

feat: improve tx-patterns-transfer document based on @ehenrka feedback

4a71e88

chore: update headings to be more consistent with other docs

7595cbd

chore: update TOC

8bbf11b

lewisdaly force-pushed the feat/3p-api branch from a7c7bf7 to 99b25e9 Compare October 5, 2021 02:32

henrka reviewed Oct 11, 2021

View reviewed changes

lewisdaly added 4 commits October 12, 2021 11:01

fix: 3p-api formatting based on @ehenrka's feedback

65e603f

fix: 3p-api formatting based on @ehenrka's feedback

a2f7f27

fix: 3p-api formatting based on @ehenrka's feedback

d915f9c

fix: 3p-api formatting based on @ehenrka's feedback

e20ad37

lewisdaly added 2 commits October 12, 2021 13:22

chore: minor fixes and typos

455f223

chore: minor fixes and typos

255833a

lewisdaly mentioned this pull request Oct 12, 2021

feat(thirdparty)!: changes for latest API draft mojaloop/api-snippets#113

Merged

lewisdaly and others added 4 commits October 15, 2021 10:51

feat: update swagger docs to latest version

ce493e8

feat: add recommendation for GET /services/{ServiceType}

2b60c4f

feat(openapi): update to latest thirdparty openapi spec

e342941

Merge branch 'master' into feat/3p-api

c1a002d

Merge branch 'master' into feat/3p-api

cbcecaa

lewisdaly merged commit 87b78af into mojaloop:master Nov 9, 2021

lewisdaly deleted the feat/3p-api branch November 9, 2021 12:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add thirdparty api specification and supporting docs #90

feat: add thirdparty api specification and supporting docs #90

lewisdaly commented Jul 20, 2021 •

edited

Loading

elnyry-sam-k commented Jul 20, 2021 •

edited

Loading

lewisdaly commented Jul 20, 2021

lewisdaly commented Oct 5, 2021

henrka commented Oct 11, 2021

lewisdaly commented Oct 11, 2021 •

edited

Loading

henrka left a comment

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

henrka Oct 11, 2021

lewisdaly commented Oct 12, 2021

henrka commented Oct 12, 2021

elnyry-sam-k commented Nov 5, 2021

henrka commented Nov 9, 2021

lewisdaly commented Nov 9, 2021

elnyry-sam-k commented Nov 9, 2021


		##### 3.1.1.1 Requests

		This section describes the services that a PISP can request on the /accounts resource.

Type of Information	Convention	Example
Elements of the API, such as resources	Boldface	/authorization
Variables	Italics with in angle brackets	{ID}

		the PISP.


		1. _let `consentId` be the value of the `body.consentId` in the POST /consents request_


		## <a id='DerivingtheChallenge'></a>6.1 Deriving the Challenge

		1. let `quote` be the value of the response body from the PUT /quotes/{ID} call


		## <a id='badpayeelookup'></a> 5.1 Unsuccessful Payee Lookup

		<!-- TODO: update these sequences with updated error codes -->

feat: add thirdparty api specification and supporting docs #90

feat: add thirdparty api specification and supporting docs #90

Conversation

lewisdaly commented Jul 20, 2021 • edited Loading

elnyry-sam-k commented Jul 20, 2021 • edited Loading

lewisdaly commented Jul 20, 2021

lewisdaly commented Oct 5, 2021

henrka commented Oct 11, 2021

lewisdaly commented Oct 11, 2021 • edited Loading

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

lewisdaly commented Oct 12, 2021

henrka commented Oct 12, 2021

elnyry-sam-k commented Nov 5, 2021

henrka commented Nov 9, 2021

lewisdaly commented Nov 9, 2021

elnyry-sam-k commented Nov 9, 2021

lewisdaly commented Jul 20, 2021 •

edited

Loading

elnyry-sam-k commented Jul 20, 2021 •

edited

Loading

lewisdaly commented Oct 11, 2021 •

edited

Loading