Document that there is no batch REST endpoint to list code owners for multiple paths
The question about a batch REST endpoint to list code owners for
multiple paths at once has come up multiple times now and it's better we
document why such a REST endpoint isn't there and what callers are
expected to do instead.
Signed-off-by: Edwin Kempin <ekempin@google.com>
Change-Id: Ibb8689c9c69cbd745694b1444674c7d14226a70f
diff --git a/resources/Documentation/rest-api.md b/resources/Documentation/rest-api.md
index a1059b3..f6cd213 100644
--- a/resources/Documentation/rest-api.md
+++ b/resources/Documentation/rest-api.md
@@ -407,6 +407,23 @@
]
```
+#### <a id="batch-list-code-owners"> Batch Request
+
+There is no REST endpoint that allows to retrieve code owners for multiple
+paths/files at once with a single batch request, but callers are expected to
+send one request per path/file and do any necessary grouping of results (e.g.
+grouping of files with the same code owners) on their own.
+
+To ensure a stable sort order across requests for different paths/files it's
+possible to set a seed on the requests that should be used to shuffle code
+owners that have the same score (see `seed` request parameter above).
+
+To speed up getting code owners for multiple paths/files callers are advised to
+send batches of list code owners requests in parallel (e.g. 10) and start
+processing the results as soon as they come in (this approach is faster than
+having a batch REST endpoint, as the batch REST endpoint could only return
+results after the server has computed code owners for all paths).
+
## <a id="change-endpoints"> Change Endpoints
### <a id="get-code-owner-status"> Get Code Owner Status
