Decision Proposal 019 - Discoverability

[JamesMBligh]

This decision proposal outlines a recommendation for the end points and payloads for publicly available end points that allow discovery of the state of a specific CDR implementation.
Decision Proposal 019 - Discoverability.pdf

Feedback is now open for this proposal. Feedback is planned to be closed on the 29th March.

[perlboy]

Not sure this is the right place but has there been any thought given regarding the introduction of discoverability for supporting services? I ask because initially CDR isn't going to have write access but at least a "supported providers" list could be supplied? That is to say things like NPP Payment Initiation gateways (data holders or Osko) and/or BPAY initiation (for non NPP) for example. That could lend itself to data recipients being aware they might have access to additional capability (albeit commercial).

[rohgoyal]

Current standard is published as one big Swagger, has there been any thinking around breaking it for better version management, managing set of resources (e.g. Accounts) independent to others (say customer) and possibly to enable access control in future?

[perlboy]

Current standard is published as one big Swagger, has there been any thinking around breaking it for better version management, managing set of resources (e.g. Accounts) independent to others (say customer) and possibly to enable access control in future?

This isn't the right place for this and if I understand what your question is much of it has been discussed in closed/feedback closed issues (including the #39 which is related to the standard you reference). Please familiarise yourself with the existing material and note that the last update I'm aware of is the team are processing the submissions and will come back with a second standard.

All issues:
https://github.com/ConsumerDataStandardsAustralia/standards/issues?utf8=%E2%9C%93&q=is%3Aissue

[rohgoyal]

Current standard is published as one big Swagger, has there been any thinking around breaking it for better version management, managing set of resources (e.g. Accounts) independent to others (say customer) and possibly to enable access control in future?

This isn't the right place for this and if I understand what your question is much of it has been discussed in closed/feedback closed issues (including the #39 which is related to the standard you reference). Please familiarise yourself with the existing material and note that the last update I'm aware of is the team are processing the submissions and will come back with a second standard.

All issues:
https://github.com/ConsumerDataStandardsAustralia/standards/issues?utf8=%E2%9C%93&q=is%3Aissue

Swagger definitions are very important part of great discoverable APIs so my comment is about that. Understand your point though some of the similar thinking has been added with issue #39 .

[JamesMBligh]

The proposal for this issue has now been published in the issue description...

-JB-

[NationalAustraliaBank]

Thank you for publishing the Discoverability proposal and for the feedback opportunity. We feel that the proposal captures the discovery topics and themes raised during the feedback period for the URI Structure decision proposal (#2) late last year.

Our feedback on the Discoverability proposal is as follows:

meta object

Do you foresee any use of the meta object? Could it be removed, in line with the optionality specified in decision #12?

Security scope

Based on the need to know security principle, we recommend that the discovery endpoints are only available to accredited Data Recipients and CDR participants. Exposing these endpoints unnecessarily may lead into abuse of resources and data inference.

URI version

With the proposal of having the high-level CDR Standard version in the base URI of the discovery endpoints, would this place any behavioural boundaries of the CDR endpoints within the response payloads? For example, would https://<provider path>/api/cds-au/v1/discover/endpoints return only endpoints within the v1 CDR Standard?

Operation ID

How would CDR Standard versioning in the base URI impact (if any) the operation ID?

For extension endpoints, should the approach defined in the decision #3 for the extensibility model also be applied to the operation ID in order to avoid clashes with CDR Standards operation IDs?

Status endpoint

Partial failure status

We'd like the clarify that the PARTIAL_FAILURE status would be applicable when at least one API endpoint is completely unavailable, for example, the Get Account Detail endpoint. The PARTIAL_FAILURE status would not represent a scenario when a subset of the functionality for an endpoint is not available, for example, when the Get Account Detail endpoint fails for a certain account/product type but is successful for others.

Status endpoint structure

In order for the status endpoint to integrate with Data Holder's service delivery and operational process, we propose that the structure of the status endpoint can incorporate date and time attributes. For example, in the case of PARTIAL_FAILURE or UNAVAILABLE statuses, there could be multiple date and time fields to represent:

1. When the status was first detected.
2. When the status was last updated.
3. The expected date and time of resolution (optional).

This would allow Data Holders to manage the CDR Status endpoint as part of existing service delivery and service operating processes.

NFRs of discovery endpoints

In reference to the NFRs proposed in decision #21, will there be any additional NFRs applied to the discovery endpoints?

Will the discovery endpoints need to have greater availability and be isolated from other data, security, and administration endpoints to enable the Status endpoint to always respond, particularly in critical scenarios where the status is UNAVAILABLE?

[anzbankau]

Hi James,
We have a couple of comments re: Discoverability

• We believe the resource model would be nicer starting with a noun, rather than a verb (GET /discovery/endpoints -over- GET /discover/endpoints … or perhaps /discoverability/endpoints)

• "While the presenting of this end point is mandatory for a compliant data holder under the CDR regime it is possible that the response is empty. In this case of absent data from the response to this end point the client should assume that the latest version of each end point is available under the default base URI as defined by the CDR standards. " - we think that the response should be explicit and not implied.

• replace publically with publicly

• Suggest we introduce a optional partial flag on the scheduled outage endpoint to indicate where only certain endpoint are available e.g one information store is being patched and some endpoints may be unavailable.

[WestpacOpenBanking]

We note that the proposal cites functionality of the directory to store a base URI. We believe that the most pragmatic approach would be to extend this functionality to store and share a set of base URIs similar to those identified in the proposal. This would be implemented as an endpoint at the directory. This endpoint should be authenticated to reduce the risk of base path manipulation by a malicious third party. The directory approach would require a mechanism to for data holders to update the set of baseURIs.

We support the current list of base URIs assuming that the following interpretation (previously noted) of the infosec profile is correct:

• The following authorisation endpoints are TLS only:
  • Authorisation Endpoint
  • OpenID Provider Configuration Endpoint
  • JWKS Endpoint
• The following authorisation endpoints are TLS where clients provide a signed JWT using a ACCC client certificate which is not required to be validated during the TLS handshake:
  • Backchannel Authorisation Endpoint
  • Token Endpoint
  • Userinfo Endpoint
  • Introspection Endpoint
  • Revocation Endpoint
  • Client Registration Endpoint
• The resource endpoints are TLS-MA using a ACCC issued client certificate which should be validated and that there is no other alternative method supported (e.g. TLS with a signed JWT using a client certificate).

If the interpretation above is not correct, then we are still supportive provided that endpoints using TLS transport security are allowed a different base URI path to those with TLS-MA transport security.

Finally, we have the following suggestions:

• Unless the discoverability endpoint is located at the directory, data consumers still need a method to determine which major versions are supported by Data Holders before any version of the discoverability endpoint is called. Therefore, a method of communicating the high-level standard versions supported by Data Holders would be helpful for data consumers. A directory based approach with some extensions to the proposal may be the most elegant method of achieving this.
• In the Endpoint object definition, versions should more clearly specify that these are the endpoint versions and not the high-level standard versions.

[JamesMBligh]

Thanks for the feedback. The expectation is that the discovery API will be removed and this data will be accessible instead from the CDR Registry leaving the status and planned outages end points.

I'll be closing down feedback on this thread. Any additional feedback or points of clarification can be posted on the current open thread for feedback (#67)

[JamesMBligh]

Please find attached the final decision covering this issue
Decision 019 - Discoverability.pdf