[DOC] Error responses missing in REST API documentation

opensearch-project / documentation-website

The documentation for OpenSearch, OpenSearch Dashboards, and their associated plugins.

https://opensearch.org/docs

Apache License 2.0

67 stars 465 forks source link

[DOC] Error responses missing in REST API documentation #7791

Open imvtsl opened 1 month ago

imvtsl commented 1 month ago

What do you want to do?

[x] Request a change to existing documentation
[ ] Add new documentation
[ ] Report a technical problem with the documentation
[ ] Other

APIs in the documentation show response for success scenario. Responses for error scenarios are not added.

Consider this as an example. Response body is missing for error status codes like 4xx, 5xx, etc.

Refer this issue.

hdhalter commented 1 month ago

@imvtsl - Thanks for submitting an issue, @imvtsl! Can you please check the link above (this issue), as I think you may have added the wrong link.

imvtsl commented 1 month ago

Hi @hdhalter Thank you for pointing out! I corrected the link now.

Naarcha-AWS commented 1 month ago

@dblock and @imvtsl: Would a page of common response codes be a good solution for this issue?

imvtsl commented 1 month ago

APIs are not consistent with the error responses. For example, delete document API. See this issue for more details. Therefore, a page of common error responses would not work for all APIs.

kolchfa-aws commented 1 month ago

Ideally, error messages should be consistent and self-explanatory. If they are, then we'd only need to provide the possible HTTP response codes in the troubleshooting section. We should try to fix this at the product level.