added docs for /entities/by-refs

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
2022-12-20 12:02:04 +01:00
parent 412b5f5ad2
commit 413767a5f1
1 changed files with 31 additions and 0 deletions
@@ -246,6 +246,37 @@ value. These are special in that they form the entity's unique
 The return type is JSON, as a single [`Entity`](descriptor-format.md), or a 404
 error if there was no entity with that reference triplet.

+### `POST /entities/by-refs`
+
+Gets a batch of entities by their entity refs. This is useful in contexts where
+you want to fetch a large number of specific entities efficiently, for example
+in GraphQL resolvers.
+
+The request body is JSON, on the form
+
+```json
+{
+  "entityRefs": ["component:default/foo", "api:default/bar"]
+}
+```
+
+where each entry is an entity ref that you want to fetch.
+
+The return type is JSON, on the form
+
+```json
+{
+  "items": [
+    { "apiVersion": "backstage.io/v1alpha1", "kind": "Component", ... },
+    null
+  ]
+}
+```
+
+where the `items` array has _the same length_ and _the same order_ as the input
+`entityRefs` array. Each element contains the corresponding entity data, or
+`null` if no entity existed in the catalog with that ref.
+
 ## Locations

 TODO