Horreum OpenAPI Errors Management

[lampajr]

In the past days I spent some time analyzing how horreum client could manage API errors in a clean way, and I found out that it should be sufficient to describe error responses (along with the status codes) in the OpenAPI spec that we use to generate them.

Given that, I see two main issues:

• Right now all (or at least most of) the endpoint describe the 200 response, completely ignoring the other status codes like 401 or 400 , thus we should set them for all endpoints (maybe there is a way to set a default for every one?)
• The Kiota generator doesn not seem to support text/plain as error response body and atm Horreum always return that type of content for errors

Given the previous two issues, here my proposal:

1. Define a custom error object containing a statusCode and an errorMessage
2. Make all services return that whenever something goes wrong
   • This way the error content would be application/json , more coherence as regardless of the success or not of the request the result would be in the same format
   • This should be pretty easier for custom exception as we will simply need to change ServiceException to set as entity the new obj
   • We should ensure that all other exceptions like IllegalArgumentException or any unchecked one will be converted to the new custom error (I guess there is a way in Quarkus for that)
3. Change horreum-api endpoints to return the new schema error obj

I can provide a very minimal PoC in a pull request to showcase the proposal much more concretely.

[johnaohara]

@lampajr I think this is an important improvement for the API, especially as we integrate with an increasing number of systsems and tools. I think the areas that would need to improve would be;

• Implement custom jakarta.ws.rs.ext.ExceptionMapper classe(s) to handle the different Exceptions. We may need to wrap more than just ServiceException
• Remove all unchecked Exceptions from the API code path
• Verify/Change all api points that they are returning the correct response according to the HTTP RFC.
  • e.g. as defined in: https://www.rfc-editor.org/rfc/rfc9110.html#name-post A POST response should "SHOULD send a 201 (Created) response containing a Location header field", whereas Horreum currently returns Response.status(Response.Status.OK).entity(reponseString).build(); for io.hyperfoil.tools.horreum.svc.RunServiceImpl.addRunFromData()

[lampajr]

Yeah I agree, as you highlighted it will be a huge refactoring from the API specification point of view.