search

ConsumerDataStandardsAustralia / standards-maintenance

This repository houses the interactions, consultations and work management to support the maintenance of baselined components of the Consumer Data Right API Standards and Information Security profile.
41 stars 9 forks source link

Register API error codes need to be aligned with the CDS standardised error codes #510

Closed CDR-API-Stream closed 1 year ago

CDR-API-Stream commented 2 years ago

Description

The Register API error codes haven't been updated alongside the updates to the CDS error codes as conducted through DP 120 and documented in: https://consumerdatastandardsaustralia.github.io/standards/#error-codes. As a result of this, there is an inelegance where the current swagger definitions conflict with optional code usage. This negatively affects the usability of these APIs

An example of this is as follows:

Response codes for GetSSA:

image

Potentially conflicting error codes as defined in the CDS (note the MAY requirement)

image

Alignment to these error codes should be sought for completeness and to improve usability.

Area Affected

Register APIs

Change Proposed

Audit response codes and update alignment to the CDS error codes.

CDR-API-Stream commented 2 years ago

To address this issue, an audit has been performed on the register response error codes.

Proposal:

The following changes are proposed to ensure consistency between the CDS error codes and the Register API swagger definition.

The following represent the API associated error codes which will be added or updated:

API Version Updated Error Codes New Error Codes
Get Data Holder Brands V2 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Data Holder Brands Summary V1 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field

404:
~Industry Not Found~
Invalid Industry
Get Software Statement Assertion (SSA) V3 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field

403:
~Invalid BrandId~
The ADR or the ADR's Software Product is not active

404:
~Invalid Software Product~
Invalid Industry / Invalid Brand Id / Invalid Software Product Id		  
Get Data Holder Statuses V1 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Software Products Statuses V2 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Data Recipients Statuses V2 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Data Recipients V3 400:
~Missing Required Header / Invalid Version / Invalid Path Parameter~
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry

These changes will only apply to the new Register API versions, with the dependency date of 15th November 2022.

Please refer to the Register Dependency Schedule for details.

One outstanding question is how the 422 error code defined in the Get Software Statement Assertion (SSA) V3 API should be specified. The ACCC will need to provide input as to whether the 422 error code is utilised and therefore should be specified in the CDR Register section of the error codes specification in the CDS, or, is redundant and therefore should be cleared up.

perlboy commented 2 years ago

Testing by both AEMO/ACCC for energy sector is scheduled to start in July. Will these changes be applied before, during or after industry testing has occurred?

ACCC-CDR commented 2 years ago

The ACCC requests that this issue be restricted to resolving documentation errors related to the usage of the CDR Register Errors of the CDS. While the ACCC supports the changes detailed above,we proposed that these should be revisited in a future maintenance iteration and implemented post the 15th November 2022.

The ACCC confirms that the 422 error code for the Get Software Statement Assertion (SSA) V3 API is superfluous and can be removed.

@Perlboy the ACCC does not plan to conduct any specific energy sector testing with participants beyond the Conformance Test Suite. There are however tools available to assist energy participants with their build and test, including the Participant Tooling mock solutions and the soon-to-be-released CDR sandbox.

API

Version

Updated Error Codes

New Error Codes

Get Data Holder Brands

V2

404:
Invalid Industry

Get Data Holder Statuses

V1

404:
Invalid Industry

Get Software Statement Assertion (SSA)

V3

404:
Invalid Software Product
Invalid Industry / Invalid Brand / Invalid Software Product

Get Software Products Statuses

V2

404:
Invalid Industry

Get Data Recipients Statuses

V2

404:
Invalid Industry

Get Data Recipients

V3

404:
Invalid Industry

CDR-API-Stream commented 1 year ago

Thanks @ACCC-CDR and @perlboy for your input.

Proposal

The DSB proposes to specify the appropriate error codes for the CDR Register APIs to align to the Standards error codes. These changes will be incorporated into future versions of the CDR Register APIs. Current versions will not be impacted.   The rationale for not incorporating this change into the current versions of the CDR Register APIs is due to the low priority of this change. The motivation for this change is to align the CDR Register APIs to the API conventions laid out in the Consumer Data Standards. These changes are low priority and will not be incorporated into V1.18.0, to minimise this implementation burden on participants.

The error codes to be adopted in a future version are:

API Updated Error Codes New Error Codes
Get Data Holder Brands 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Software Statement Assertion (SSA) 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field

403:
The ADR or the ADR's Software Product is not active

404:
Invalid Industry / Invalid Brand Id / Invalid Software Product Id		  
Get Data Holder Statuses 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Software Products Statuses 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Data Recipients Statuses 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry
Get Data Recipients 400:
Missing Required Header / Invalid Header / Invalid Version / Invalid Field		 404:
Invalid Industry

Note that GetDataHolderBrandSummary is not specified as this API already aligns to the error code conventions

CDR-API-Stream commented 1 year ago

This issue has been staged at: https://github.com/ConsumerDataStandardsAustralia/standards-staging/pull/202