API specification is incomplete - where are the 404 return types?

[ReinderReinders]

The Visma.net API documentation clearly states that the Swagger page (and the specification.json file hosted beneath it) can be taken as documentation for the working of the Visma.net API. There is no other documentation available and everyone points to the Swagger as the leading (and, I assumed, complete) documentation of the API. In that case, receiving 'undocumented' return types / objects back from the API should not be possible.

I noticed just now (using /api/v1/paymentmethod/{paymentMethodNumber} as a use case) that 404 (NotFound) is not among the documented possible API return types:

This breaks tooling that automatically generates a client based on the API swagger page / specification file.

As a standard, documentation that is complete should document all possible API call return types, including at the very least 404 (NotFound) and 500 (Unhandled Error). Additionally I did not realise before (tested the API before a couple of times and forgetting to log in) that the 401 (Unauthorized) return type is also not documented.

This does not apply to this single example but, as far as I can tell so far, is an API-wide issue on (nearly?) all API calls.

Please evaluate the API and update the data contracts to include all possible return types. It is very difficult to work with (auto)generated code based on incomplete API specification, and due to the size of the API it is very undesirable to implement every API call manually.

[Yıldırım]

Hello, thank you for reporting this, we'll look into that and inform the related team for the clarification.