Various Issues with the API Gov Site

[jandkw99]

Hi,

I work for a utility in Queensland. We use this standard as a reference for our API standards. I am currently implementing error handling for internal APIs and came to the site to look at how we might implement our error response. Other than the Error Response page, I was looking for an OAS definition of the Error response schema. Looking at your examples linked from https://api.gov.au/apis, none of the top 3 implement your schema described here: https://api.gov.au/sections/error-handling.html. In fact those examples are pretty poor with very basic error schemas or invalid examples and the OAS definition of the error response (particularly 500 error) for the first example not even looking to be valid (perhaps it is a old version of the openAPI/Swagger spec and I'm just not familiar with its limitations). Please update your examples to be a true reflection / reference implementation of your current standards.

Also note that the Get Started button linked from the Community page is broken with a link to: https://community.digital.gov.au/c/api

Looking at the Error response (described on the error handling page), I'm wondering if this standard should be extended to enable additional information to be passed to the client for internal API error consumers? I see that there is mention of extending the implementations of the reference standard. Currently we've been using an array of strings to contain (stack) details of the error. In our environment we use a multilayered API approach which means that errors can bubble up from potentially 5 layers below before being returned to the consumer. Each layer potentially wraps errors (all standardised JSON) which therefore requires JSON string encoding at each layer and consequently makes the messages difficult for a human to decipher (with significant escaping of JSON reserved characters). There is however an OAS free-form object type which could be used to encapsulate errors from previous layers without encoding. Just wondering whether the Australian standard could be enhanced to add something like this? The reason to provide the additional information is to enable API consumers to better self-serve on error resolution when manual intervention is required obviously this is different, in some ways, to external consumers which have less ability to resolve issues with backend systems.

Appreciate the efforts in attempting to set some standards in this space. Hopefully we can expand on this to make improvements to broaden the usage of this useful reference material.

Regards,
Jason