Decision Proposal 001 - API Principles

[JamesMBligh]

This decision proposal outlines a recommendation for the guiding principles for the development of API Standards. The detail for the proposal is in the attached PDF.

Feedback is now open for this proposal. Feedback is planned to be closed on the 10th August.
Decision Proposal 001 - API Principles.pdf

The finalised decision for this topic has been endorsed. Please refer to the attached document.
Decision 001 - API Principles.pdf

[gauravve]

Agree with the document. May be we can go a bit more specific around error codes vs status codes? It will be beneficial for us to agree on a set of business error codes across the industry? For eg payment and account errors?

[damircuca]

Agree on the recommendation to go with "Option - 3" feels logical and natural. It is difficult to adapt someones guidelines blindly without understanding what their mandate was (or discussions that took place).

Can you consider the following points in the Technical Principles section:

APIs are versioned
The API should be version controlled to ensure new features and changes can be rolled out without impacting existing users (support backward compatibility).

APIs should be discoverable
We don't have to go full blown HATEOS, but we should ensure that developers don't have to hard-code anything other than the root url. The rest should be "discoverable" by simply navigating the structure. I think this is an important technical principle that will force us to consider the placement, communication and navigation of the resources.

[ghost]

These look to set a good general direction for the details to follow. One other suggestion I would make is to include some guidance on richness of APIs. Although the scope of Open Banking is recommended in chapter 3 of the review, there will be discussions around the details of what to include/exclude (richness) as part of other decision proposals. I feel a guiding principle, presumably leaning towards richer APIs, would assist here.

[davidthornton]

Further to @mattp-rab’s point, I’ve seen a worrying trend of using opaque IDs. Particularly when it comes to scheme messages, if we don’t get the exact transaction ID, and be able to link it to other scheme update messages — we might as well save the hassle and expense of building, certifying and launching a bank API.

[speedyps]

I think the document provides a good solid direction, and I wholeheartedly agree with not reinventing the wheel.
With regards to @damircuca, its a pity that the UK Open Banking has the versioning in the basics section, not in the principles

Resource URI Path Structure
The resources defined by these APIs may be addressed through a path structure consisting of the following parts:

An optional ASPSP specific path prefix
The constant string "open-banking"
The version of the APIs expressed as /v[major-version].[minor-version]/
The resource name
Examples:

/superbank/open-banking/v2.0/payments

/open-banking/v2.0/account-requests

/apis/open-banking/v2.1/accounts

[davidthornton]

Before we get too prescriptive on versioning, I think it's worth mentioning how Stripe does it. They have no version number in the URLs, but do a thing called version pinning where the version is controlled from the user dashboard.

This is really advanced, and future proof -- something we want to look to as a role model. Have a look at it here: https://stripe.com/blog/api-versioning

We maintain Docker images of each commit from the tip of master, and while we haven't trotted it out to production, we would like to in future.

[davidthornton]

I've just re-read it and I think you can trigger an API update though the API (such as on a deploy hook. Wow!)

[deboraelkin2]

Agree with the overall principles reflected in the document. I strongly support @speedyps proposal on adding URI path structure, including versioning at the resource group level. Explicitly including the versioning in the URI path makes it easier for a developer to understand which version is being used

[JamesMBligh]

This decision was open for feedback until the 10th which is now only a few days away. As such, I thought it would be wise to give a response to some of the feedback given to date so that everyone gets a second bite at arguing any specific case they are passionate about. If this works then I will likely follow the same protocol for subsequent decisions.

So here is my response to the key items of feedback provided...

Versioning
The idea of a principle for versioning is a good one. This will be seriously considered for addition. For the more detailed concerns around versioning I will defer these to the versioning decision that is coming. At this stage I will say that the API versioning strategy is planned to take into account the kind of flexibility provided by Stripe (although Client pinning is a bit hard to mandate when the relationships to be established are many-to-many). Feedback from multiple sources to Farrell report indicated that block versioning of the API (as critiqued by @speedyps) is inflexible.

Discoverability
The value of discoverability in a standard that is likely to have a strict compliance mandate with central documentation is arguable. I will leave further comment for the thread on the URI structure as it is more relevant there but, at this stage, an additional principle for discoverability is not likely. This does not mean that discoverability will be ignored, just that it isn't a first order concern for this standard. Happy for more feedback on this topic of course.

API Richness
This is a reasonable concern but it could be argued that is covered by the principles relating to User and Developer experience that demand, effectively, that the APIs be useful and easy to use for a variety of real world problems. If I understand correctly this is the driver for a richness principle, that the APIs not be too constrained or minimal. I hope I got that right.

Thanks everyone for your contributions. It's been very encouraging reading such considered and well thought out feedback.

-JB-

[bazzat]

The ABA Open Banking Technical Working Group has discussed the question of discoverability of API's. The consensus position appears to be as follows:

"As in the UK, standard should enforce discoverability principles wherever pagination of responses is allowed (see https://openbanking.atlassian.net/wiki/spaces/DZ/pages/127009221/Read+Write+Data+API+Specification+-+v2.0.0#Read/WriteDataAPISpecification-v2.0.0-Pagination)

Otherwise, we agree with James' comments on discoverability. Although elegant, the value in the context of a strict, well documented technical standard is limited. The downsides outweigh the upsides when the additional complexities defining and implementing the standards are considered. It wouldn't be difficult to add it to a later version of the standard if a clear use case is eventually discovered."

[TKCOBA]

The Customer Owned Banking Association (COBA) welcomes the opportunity to comment on Data61’s Decision Proposal 001 API Principles.

COBA is the industry association for Australia’s customer owned banking institutions (mutual banks, credit unions and building societies).

In general terms, COBA supports Data61’s approach to define a list of principles tailored to the specific needs of the Australian Consumer Data Standards.

With respect to versioning, COBA notes stakeholder comments posted on this matter. COBA supports the concept of incorporating an explicit principle for versioning. We also look forward to considering Data61’s detailed decision proposal on versioning when it is released for comment.

COBA also notes stakeholder comments in relation to API richness, including Data61’s view that it could be argued that this is covered by the proposed principles relating to user and developer experience (principles 3 and 4).

COBA supports the incorporation of an explicit guiding principle to help promote richer sets of data in the development of APIs, to help ensure that the APIs are not unnecessarily constrained or minimal (as pointed out by Data61). A good breadth of information would help support innovation, for example, which would align with the intended objectives of Open Banking. With that said, COBA is not suggesting that this should be a strict rule, given the complexity of the commercial decisions involved.

COBA recognises that detailed consultation on the scope of data for Open Banking will be undertaken at a later stage. However, COBA’s view is that having in place an overarching guiding principle on richness would also help facilitate the detailed consultation on scope.

Furthermore, COBA notes and supports API Principle 10: APIs are extensible, that API definitions and standards should be built for extensibility (e.g. to accommodate future API categories). However, if possible, COBA would also like to see an additional principle that preserves backwards compatibility.

[davidthornton]

At least the ABA is represented by a personal profile!

I wholeheartedly believe that Data61 has opted to use GitHub to develop a standard because the forum is conducive to efficient, informal discussion to converge quickly on the operative issues.

Allocating four paragraphs for industry background (regardless of affiliation for customers or incumbents) is totally unacceptable in this forum.

This is a technical standard and should be treated as such. It should be contributed to by technically minded individuals. Not boilerplate spouting industry lobbyists.

To summarise, your comment adds entirely nothing to the discussion of developing a technical standard and therefore should be disregarded in toto.

Please refrain from further polluting a productive discussion upon standards.

[JamesMBligh]

I’m afraid I disagree David. It is true we used GitHub for the reasons you mentioned but it has to be acknowledged that what we are doing here is different to a normal technical standard.

There are numerous stakeholders and some of them, by their nature, need to communicate as a group rather than as an individual. Some individuals can’t contribute due to the policies of their employers. This was expected and flagged in advance in the README.

I found the comment helpful and not a pollution of the dialogue and I would encourage this form of feedback in the future as much as I would encourage feedback from individuals.

If the dialogue does become unhelpful I’m more than happy to step in and moderate.

-JB-

[davidthornton]

Duly noted

[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 001 - API Principles.pdf