-
Notifications
You must be signed in to change notification settings - Fork 56
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Decision Proposal 002 - URI Structure #2
Comments
"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
|
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
My recommendation is to actually not enforce a particular URL structure ( e.g.
Returns:
Some other feedback:
|
@damircuca + @JamesMBligh |
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. |
@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. |
Hi Damir, yes I was referring to payload size although likely not a significant concern. Do like ralphbraggs discovery document also. Cheers |
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 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
where domain is a further grouping within a given industry (eg: retail, wholesale for banking) |
Some comments to consider:
|
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? 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? |
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. |
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. |
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)? |
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- |
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. |
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? |
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. |
@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? |
Matt, I would probably lean on Principle 2 (widely used open standards) and Principle 7 (keep things simple to reduce implementation costs). -JB- |
@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: 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: |
I have now closed consultation on this decision. A recommendation incorporating feedback will be made to the Chair in due course. -JB- |
The finalised decision for this topic has been endorsed. Please refer to the attached document. -JB- |
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
The text was updated successfully, but these errors were encountered: