Decision Proposal 015 - Account/Transaction End Point Structure (specific URIs)

[JamesMBligh]

This decision proposal outlines a recommendation for the URIs for account/transaction API end points. This proposal overlaps significantly with the ACCC rules so it has been authored to align with the proposed rules framework as much as possible.

Feedback is now open for this proposal. Feedback is planned to be closed on the 5th October. Decision Proposal 015 - Account-Transaction End Points.pdf

[da-banking]

These endpoints are broadly as expected and acceptable, with the following observations:

• Similar to the inclusion of direct debits, the UK specifications include the ability to retrieve recurring and future-dated payments. Including this would be good for driving portability of banking arrangements.

• As per the outcome for #8 - we believe that POST /banking/accounts/balances should be POST /banking/accounts/balances/search. This would be for consistency with other POST queries only - a balance is a field derived from transactions occurring on the account, and there would never be a need to POST an update to the balances resource.

• For the GET /banking/accounts/{accountId}/directdebits endpoint, it is unclear to us why pagination has been excluded. There is no hard limit to the number of direct debits an individual account can have, and this endpoint should therefore be designed with that in mind. Since we are already paginating GET /banking/accounts/directdebits, it seems there are no technical reasons preventing us paginating the account-specific call. We would go further and recommend that pagination be standardised on all collection endpoints.

• The UK specifications define direct debits with hyphen-delimited terms: GET /accounts/{accountId}/direct-debits and GET /direct-debits. The proposal omits the hyphens. We don't think an approach has been covered yet with regard to how to delimit multi-word terms in the names of resources, and would recommend the use of hyphens as per the JSON API recommendations.

[JamesMBligh]

Thanks @da-banking. All valid feedback. Paging for direct debits is a good idea and a standard for multi word resource names is needed.

Regarding payments - this data is not currently listed in scope in the draft ACCC rules framework so I haven't included it in the proposal.

Regarding the POST for balances, the decision regarding pluralisation indicates that a complex query should be a POST on a sub-resource so that a POST can still be used for creation of a collection member. In this case "balances" is not the collection, "accounts" is the collection so applying the POST to "balances" in this manner is aligned to the previous decision.

-JB-

[deboraelkin2]

Given previous discussions around complex searches being handled via POST verbs, I think it would make sense to also include POST /banking/accounts/transactions POST /banking/accounts/{accountId}/transactions

This would allow to implement complex search functionality on transactions, such as find all debits made in the last 30 days where the description includes XXX and the amount is greater than $10. Of course, this may prove redundant if the parameters for the corresponding GET operations can handle such type of queries.

[WestpacOpenBanking]

Westpac broadly supports the decision proposal. We have the following remarks and questions:

• Unlike the UK, direct debit authorities are not held by banks in Australia. ABA members have committed to give customers a list of direct debits known to them through information received about transactions from 1 July 2019. There are risks of misinterpretation of the derived and incomplete nature of this list.
• Endpoints which collate resources across multiple accounts, like GET /banking/accounts/transactions, may introduce implementation inconsistencies if the standard is not carefully written. For example, what is the ‘correct’ ordering when transactions from multiple accounts are included if there is only associated date and no time information for some transaction types?
• Is it intended that filtering will typically be restricted to the most natural fields for a resource type (e.g. dates and times for transactions) or that it will allow more complex queries (i.e. a search)?
• There is a namespace collision between {accountId} and all other sub-resources. A naming convention stating that sub-resources must start with a lowercase alphabetic character might be a good idea.
• Given deboraelkin2’s comments. We are likely to end up with collisions between POST for complex queries and POST for resource creation in the longer term and may need to revisit decision 8. We offer three possible alternatives to consider:
  1. Complex queries are always POSTed to a “search” sub-resource, e.g. POST /banking/accounts/balances/search. (Not RESTful, but pragmatic and most aligned to decision 8)
  2. Complex queries use GETs and long query strings, e.g. GET /banking/accounts/balances?json_query={a_long_url_encoded_query_described_in_json}
  3. Complex queries are first created as resources, e.g. POST /banking/accounts/query followed by a GET /banking/accounts/balances?query_id=1234

[bazzat]

The ABA Open Banking Technical WG is supportive of this decision proposal, with a couple of comments:

• a "balance" can take many forms and not all banks will be able to provide all forms. It will be important to be able to specify exactly what kind of balance(s) is/are being returned
• we would appreciate clear guidance on which endpoints are mandatory, optional or conditional.

[DeloittePE]

Deloitte concurs with the proposal.

We note the discussion about using POST for complex searches. This aligns with an RPC-style of API request and our experience is that virtually all RESTful APIs inevitably encounter use-cases which require RPC operations. Typically these involve a search or a validation.

Our suggestion to differentiate a POST collection operation from an RPC POST operation is to use a verb to name the subresource on the associated URL. This was discussed in decision 08 with the example of the form:

POST /accounts/transactions/search

We note in this case with aggregating balances over a complex-filtered collection of accounts, that it is difficult to naturally arrange for a verb as the subresource. With pragmatism and simplicity in mind, we concur with the current proposal.

[TKCOBA]

COBA’s view is that the ‘POST’ HTTP Method would not be required. With respect to supporting pagination (a front-end driven use case), our view is that this may inadvertently encourage ‘chatty calls’ which would be detrimental in high volume use cases. On this basis, COBA suggests imposing a maximum number of response records, such as 500 for API calls (any calls beyond the maximum could be served by asynchronous options). Furthermore, there does not appear to be any reference to sorting the responses (such as. by date or description). While sorting is also a front-end driven use case, we suggest that sorting be performed at the source as this would be more efficient and would add immense value to front-end use cases.

[NationalAustraliaBank]

NAB is also broadly supportive of this proposal.

We would like to thank Data61 for hosting the meet-up earlier this week. The open conversations were useful to help understand the thinking and rationale for why and how the Australian standards may deviate from that of the UK. For the benefit of those who were unable to attend we would like to restate a few points that were discussed during the meet-up.

• As already stated in this thread, direct debit instructions which are debited from an account are not owned by the account or data holder and are originated by merchants or other third parties in Australia; Already completed direct debit instances on the other hand may conceptually be 'derived' or 'inferred' from one's transaction history, however, the data holder does not hold the source data or instruction details. As such, only a limited subset of meta-data may be available, and will be inconsistent and unreliable at best. Is the intention to provide information regarding regular or scheduled payments where the data holder is the initiator of the instruction? Further clarity of the intention of this end-point is required.

• Should there be a resource for 'balances' of a single account (i.e. /banking/accounts/{accountId}/balances to be consistent with 'transactions'?).

• We agree with the feedback provided by WestPac regarding the use of the multi-account transaction history search. This again is technically possible but may introduce non-essential complexity from a pragmatic MVP perspective. The other resources described provide the basis for meeting the emerging legislation and rules that are applicable to the CDR.

[perlboy]

Hi there,

Aware that the comment period closed yesterday I'll keep this short.

I agree with the proposal as it stands, the only thing I would note is the explicit definition of /directdebits.

This implies a specific product type that allows direct debits. Other account types classify these as automatic payments such as scheduling EFT or BPAY. Additionally each payment method has it's own submission requirements. Maybe this can be all modelled into a generic payee details but this could lead to unintended consequences too.

Is it the projects intention to make additional endpoints for each payment type? It seems like over time the namespace could get quite polluted? Perhaps a child URI (/payments/[paymenttype]) is a little more future proofed?

Thanks,

Stuart

[JamesMBligh]

Response to the feedback is as follows...

Payloads Some of the feedback is actually related to the specific workings of the end points via the payloads and query parameters. I will defer responding to this feedback until the payload proposals begin to be put forward.

POST For Transactions I will include this for completeness. If the query terms do not warrant it then we can always drop it.

Mandatory End Points All end points included are considered mandatory for compliance.

Sub-resource vs Verb For the complex queries, this was addressed in a previous decision and I have responded above. A non-collection sub-resource will work as a holder for a complex query, especially if that is the data being sought. If the main collection data us being sought then a dedicated sub-resource (i.e. a verb) will need to be introduced. This will make me feel itchy and in need of a shower but it will likely be necessary.

Sorting The inclusion of sorting is a good callout. This would need to be considered alongside the filtering criteria.

Chatty Calls I think this should be able to be addressed by NFRs and the fact the differentiation between number of calls allowed when a user is logged in or disconnected. When w come to NFRs we may need to be explicit about what the community of providers and consumers of data consider to be anti-social behaviour so that apps don't get too chatty.

Direct Debit In this context, Direct Debit does not refer to a DE of Transfer style payment. It refers to an authorisation given to a 3rd party to directly debit an account (say to pay a utility bill).

-JB-

[JamesMBligh]

I have now closed consultation on this decision. A recommendation incorporating feedback will be made to the Chair in due course.

-JB-

[JamesMBligh]

The finalised decision for this topic has been endorsed. Please refer to the attached document. Decision 015 - Account-Transaction End Points.pdf

-JB-