[GitHub] [druid] suneet-s commented on a change in pull request #10967: Add missing API references for coordinator

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

suneet-s commented on a change in pull request #10967:
URL: https://github.com/apache/druid/pull/10967#discussion_r609152814



##########
File path: docs/operations/api-reference.md
##########
@@ -157,19 +157,37 @@ If no used segments are found for the given inputs, this API returns `204 No Con
 
 ##### GET
 
+* `/druid/coordinator/v1/metadata/segments`
+
+Returns a list of all segments for each datasource enabled in the cluster.
+
+* `/druid/coordinator/v1/metadata/segments?datasources={dataSourceName1}&datasources={dataSourceName2}`
+
+Returns a list of all segments for one or more specific datasources enabled in the cluster.
+
+* `/druid/coordinator/v1/metadata/segments?includeOvershadowedStatus`
+
+Returns a list of all segments for each datasource with the full segment metadata and an extra field `overshadowed`.
+
+* `/druid/coordinator/v1/metadata/segments?includeOvershadowedStatus&datasources={dataSourceName1}&datasources={dataSourceName2}`
+
+Returns a list of all segments for one or more specific datasources with the full segment metadata and an extra field `overshadowed`.
+

Review comment:
       All the API docs are written as examples of APIs. I think this can be confusing for an end user. What do you think about collapsing all of these into a single API line in the docs. Something like
   
   ```suggestion
   * `/druid/coordinator/v1/metadata/segments[?datasources={dataSourceName1}[&datasources={datasourceName2}][&includeOvershadowedStatus]]`
   
   Returns a list of all segments for each datasource enabled in the cluster. Optionally, filtered by datasources. If `includeOvershadowedStatus` is passed, then the response will include an extra field `overshadowed`
   ```
   
   I can't tell if this is easier to understand than what you've written here. Thoughts?




-- 
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



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