[GitHub] [incubator-druid] justinborromeo opened a new issue #7422: Update API Reference doc with endpoints' request parameters and response model

[GitBox <gi...@apache.org>]

justinborromeo opened a new issue #7422: Update API Reference doc with endpoints' request parameters and response model
URL: https://github.com/apache/incubator-druid/issues/7422
 
 
   ### Motivation
   
   The existing API reference is very difficult to use since there's no documented parameters and sample responses.  Using many of the endpoints requires searching through the other docs for other places where the endpoint is mentioned and its functionality is described in greater detail.  The API reference would be much more usable if all the API specs were consolidated into one doc.
   
   ### Description
   
   I think the docs would be easier to use if each endpoint had the following information:
   - Supported HTTP Method(s) and URI
   - Description of the endpoint's functionality
   - If applicable, each parameter's name, type, and description
   - Response schema and sample response (where applicable)
   
   Currently, the API reference is all contained on one page.  With all of this added information, it would be better to split it among multiple pages.
   
   ### Discussion
   
   Since this is a decent-sized undertaking, do community members see value in changing the API reference this way?
   

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org