AnkiConnect API Feedback - Improvements Needed

[kerkmann]

Hello AnkiConnect Developers,

I have been using the API and would like to share some huge feedback and suggestions for improvement.

Status Codes and Error Messages:

I noticed that when there's an error in the API request, Anki returns a status code 200 with an error message. It would be more appropriate and consistent to utilize proper HTTP status codes for error responses, such as 400 (Bad Request) or 500 (Internal Server Error). This would help developers identify and handle errors more effectively.

Handling Empty Parameters:

Currently, it seems that the API does not allow sending "params": null when there are no parameters needed for a request. It would be more intuitive if the API allowed omitting the "params" field altogether for such cases, instead of forcing users to send an empty object. This would streamline the request process and make it more user-friendly.

Response Format for "getNumCardsReviewedByDay":

The response format for the "getNumCardsReviewedByDay" request includes data wrapped in an array, which might lead to confusion. Instead, using a JSON object for the response data would provide a clearer representation of the data being returned. And also would not mix different types in arrays which can lead to problems in static type languags.

I understand that developing and maintaining an open-source project can be challenging, and I want to express my willingness to help. But please, don't reinvent the wheel. The API is only usable with bad practice and huge workarounds (for example, wrong status/weird if else clauses based on the error field, bad structured json responses (not really deserializable out of the box)).

I believe addressing these issues would enhance the overall experience for AnkiConnect developers.

Best regards,

Daniél Kerkmann