Decision Proposal 002 - URI Structure

[JamesMBligh]

This decision proposal outlines the recommendation the base URI for all end points defined in the 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 17th August. Decision Proposal 002 - URI Structure.pdf

[gauravve]

"cds" seems to be static field not providing any value. Are there any chances of this changing in future?

Also do we need another domain field within banking? For eg

api/cds/v1/banking/retail/accounts
api/cds/v1/banking/trading/accounts

[damircuca]

Hey @JamesMBligh I was wondering if it's possible to make it a little less prescriptive with the URL structure? As I imagine different organisation will have varying requirements where they host their end-points and how they configure their DNS etc. With the proposed structure we may have duplication in the base-url (provider path) and the recommended URL paths for e.g. we may have a scenario like

https://cds-1-api.bank.com.au/api/cds/v1/*

My recommendation is to actually not enforce a particular URL structure (<provider path>). Instead state that the root (base-url) of the endpoint must return a body which includes the appropriate implementation / standard details along with the URL's to the endpoints - this would also enable service discoverability without having to hard-code URL's throughout the code. Further the spec can also include in the spec the schema of the root body which can be used to validate that it conforms to the spec.

e.g.

GET https://api.bank.com.au

Returns:

{
  "cds":{
    "country":"AU",
    "version":1,
    "industry":"banking"
  },
  "links":{
    "self":"https://api.bank.com.au",
    "accounts":"https://api.bank.com.au/accounts",
    "transactions":"https://api.bank.com.au/transactions"
  }
}

Some other feedback:

• Not sure of the purpose of "industry" should we instead reference the official specification name? Banking is very ambiguous, what about CCR, NPS and other initiatives - they can all be considered "banking".
• Including the version number of the CDS standards in the URL may confuse with the actual version of the endpoints.

[ghost]

@damircuca + @JamesMBligh Does Damir's second suggestion increase the data overhead? For example, by specifying a 'restricted' root path in the request, such as: https://cds-1-api.bank.com.au/api/cds/v1/ACCOUNTS AS OPPOSED TO a 'broader' request (e.g. GET https://api.bank.com.au) that returns a far larger set of links/ data overhead than specifying a more restrictive search term?

[RalphBragg]

Hi, a resource discovery document is the way to go rather than static coding the uri paths.

Explicitly specifying the location of the discovery document is recommended instead of the assuming that it is available in the root.

Discovery is being created now for the UK OpenBanking standards it would be good to see if we can align if possible.

[damircuca]

@webstem2 By data overhead - do you mean payload size? In regards to more restrictive search term, this shouldn't change regardless if we hard-code / enforce url structure or make them discoverable it will come down to the navigation of the resources (URI structures) - which needs to be looked into regardless.

Agree with @RalphBragg about specifying location of the discovery url instead of root - this is inline with what I was trying to suggest of being less prescriptive.

[ghost]

Hi Damir, yes I was referring to payload size although likely not a significant concern.

Do like ralphbraggs discovery document also.

Cheers

[speedyps]

As the purpose is to set a standard, reducing the amount of variation between implementations is key. I have worked on projects where the specification had gaps, and different parties (implementing and consuming) the data worked to different assumptions. It lead to a lot of rework on both sides. I like the idea of the discovery document, but also like the standard having some common rules about structure.

[deboraelkin2]

I think adding the version right after the cds-au prefix might be too broad. If a given industry needs to introduce a new version for whatever reason, that would change the version for every industry

I suggest a URI structure like this

provider path / cds-au / industry / domain / version / resource

where domain is a further grouping within a given industry (eg: retail, wholesale for banking)

[damircuca]

Some comments to consider:

• Industry - if the endpoint is being served by a bank then the base url should be descriptive enough. Also what is the standard for an industry list and what value does it add? Plus this feels like we're getting a little ahead of ourselves, nothing has been imposed on any other industry beside banking - so perhaps we should consider this later.

• domain - what if an individual account list spans multiple domains? Adding it to the URL would constrain the data model.

• version - please note that my understanding of what James has proposed is that the version is not the actual API version but the open banking spec version, which is very different - and will be misleading to the user. If a bank chooses to extend an endpoint or supply additional resources etc. it should have its own versioning scheme - where will this be reflected if we use the open banking spec version in the url?

[jeffsaul]

There are cross-industry considerations also. If an individual wants to know the personal data an organisation holds on them, aren't they supposed to be able to request this information? How would the proposed structure cater for this more generic data set? Remove the industry altogether?

There are other generic concepts across industries also that could cause confusion. An account with an energy provider is probably not the equivalent of a deposit account with a bank. Bendigo Bank also operates as a Telco. Would I have two means of obtaining personal data from such an entity?

[ggotti]

Further to @damircuca 's point, something HATEOAS/HAL-esque may be appropriate for the discovery mechanism, to ensure we're not reinventing the wheel. It'll also allow producers to add additional endpoints, depending on their needs.

[dimovn]

I am supportive of the proposal. Not sure about the domain grouping as proposed in the comments. When we get down into the API specifics e.g. for account / product, this can be consistent across domains.

[perlboy]

I agree that if one or both of the European standards have or are making active steps towards a discovery mechanism standardisation it should be adopted preferably verbatim. Given Australia's relatively small banking technology providers landscape truely facilitating multi region support is mandatory to achieve a global open banking outcome.

I think the concept of a discovery layer seed that actually determines the type of open API baselines available per installation should be mandatory. That is to say that a vendor should be able to perform a GET and not just receive cdr specific functionality (i think it's referred to as extensions in doco) but also an array of standard providers, ie. CDR endpoint at X, OpenBankingUK at Y and OpenBankProject at Z to then perform additional functionality discovery on. This could extend further into the industry specific side of things although I fear keeping the scope so wide will divert off the open-banking objective (how hard does CDR want to chew? :)).

This would facilitate a technology transition period for foreign bank entities who may have their systems delivered by head office (who have developed for OpenBankingUK et al) and rapidly make this functionality available within the local (Australian) bank entity. Outside of region specific account information much of the data model (ie. transactions) will be similar anyway.

RE: HATEOAS/HAL-esque. I like the idea of HAL-esque and HATEOAS is already well defined but I'm not personally a fan of HATEOAS. For a standard that's been around nearly 10 years there is surprisingly few decently maintained integration frameworks. Makes me question whether hitching the wagon to this as a core concept is a good idea.

Swagger/OpenAPI definition based discovery seems to be what most have settled on, is what is used by OpenBankingUK while OpenBankProject went wholesale into a different definition structure (can't remember what it's called). OpenBankProject has recently started publishing swagger definitions too although they need massaging to work effectively at the moment.

Final edit, considering Decision #1 decided to draw on multiple sources when moving forward perhaps it would be worthwhile publishing some sort of structured table to determine the standards being compared against. The Wiki is currently disabled but I'm thinking something akin to a CDR version of the Unix Rosetta stone (http://bhami.com/rosetta.html)?

[JamesMBligh]

Some excellent feedback on this topic.

I am very sympathetic to a discovery mechanism, although the majority of use cases will require specific semantics of the APIs.

I am hesitant, however, to include too much in the initial version as it could be biting off more than we can chew in the first instance. We have short timeframes and there isn’t really a standard we can pick up for this. Hence the inclusion of static URIs at the outset.

As mentioned in one post variations between implementations is an active concern. This has been an area where we have received feedback in other jurisdictions.

As for industry, we need to plan for it now. Energy and Telcos have already been flagged. Some of the comments highlight the need for cross industry considerations to be made (the Bendigo Bank example for instance).

So, the thinking at the moment is static URIs are important although the inclusion of a discovery document at a known location could be a useful addition to support discovery use cases. It would also facilitate extensibility as additional APIs could be easily advertised.

I am open to removing the static text. This was a nod to the U.K. standards which we are using as a base and also seems like a way to specifically separate APIs under this standard compared to other potential standards.

-JB-

[speedyps]

Thanks for the summary @JamesMBligh, I agree that we need to focus on what gets us up and running, and not go too big too early.

There are a lot of really good ideas, but I think one of the key goals for the initial version is to ensure we get the parties that have to implement the APIs across the line in a timely manner. This may mean being judicious about what is in the first version (even if it doesn't seem like a lot of work). Then revisit some of the other ideas in later versions.

[perlboy]

100% agree with the sentiment here. I'm not sure it's a principle but there is a definite need to "buy before build" on supporting protocols if we want to come close to hitting the timeline. Even 6 month implementation for banks seems likely to be pushed out, 100% coverage could be a 12-18 month process.

It occurred to me "Discovery" is pretty generic term though because it works across a global (something like XRDS), regional (actual CDR API implementations) and implementation specific contexts.

Global, at this stage I'd suggest XRDS being recommended maybe with an extension and then the standard can reflect accordingly. The documentation element becomes a lot easier too.

Regional to me can (and I feel should) be generically & statically mapped (ie. /accounts/{XX}) etc. with an OpenAPI definition (typically at /swagger.json). The OpenAPI models should comply with the data model in the standard (precisely) but with optionality of extension classes (tbd)?

Security based scoping can control the inclusion of potentially custom extended data. At a government level, compliance management is a bigger topic and I'm unsure if it's within scope of the working group?

[TKCOBA]

COBA is of the view that the proposal may have an unintended limiting effect on users – this would not appear to align with some of the proposed API Principles in Decision Proposal 001.

As an alternative suggestion, COBA believes that a dynamic resource discovery document would be more preferable (i.e. a single root path where there will be a document available which describes the industry, version, domain, etc.), as opposed to static coding in the URI path. This would align with the proposed guiding principles with respect to simplicity, developer experience and extensibility.

Addtionally, a dynamic resource discovery document would also help simplify the extensibility model for Data 61’s Decision Proposal 3 Extensibility Model by incorporating the proposed Provider Identifier concept.

COBA notes that other stakeholders have shared similar views.

[ghost]

@JamesMBligh it seems as though there is a fair guiding principle being followed in your reasoning, but not one that is explicit from decision proposal #1. Without a guiding principle to reference, other guiding principles would logically take precedent (e.g. extensibility). For the sake of future discussion points, perhaps there a need for an additional principle along the lines of utilising matured techniques to minimise time to market?

[JamesMBligh]

Matt, I would probably lean on Principle 2 (widely used open standards) and Principle 7 (keep things simple to reduce implementation costs).

-JB-

[christopherducci]

@JamesMBligh, I like the simplicity of your proposal, It's pragmatic and well considered.

Keen to elaborate more on the "common" industry subtype? Would this be for resources like login/consent management etc? or would this also be for resources like "Customer"? How do you imagine deciding what is common Vs. not? Could you imagine a world were different industries are running on different common resource versions. Or the possibility that banks within the same industry may run for a period of time on different versions of the same common resources?

w.r.t: <provider path>/cds-au/<version>/<industry>/<resource>

To make the scheme more globally palatable could we consider changing the static cds-au to a parameter? (Not tied to the idea, but more teasing the idea of looking beyond just Australia): in Australia we may use "cds-au" in NZ it might be something else? Well aware we need to be pragmatic too.

That said Australia is on the front foot with its Customer centric approach to Open Data, if we do a good job other countries will look at adopting our standards in future, as we have looked to the UK.

i.e: <provider path>/<implementation>/<version>/<industry>/<resource> That said the static path is not a show stopper either.

[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 002 - URI Structure.pdf

-JB-