From 413767a5f1174a41bdb0573dc875e138cfaa8928 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Tue, 20 Dec 2022 12:02:04 +0100
Subject: [PATCH] added docs for /entities/by-refs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 docs/features/software-catalog/api.md | 31 +++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index afd9a0af93..1020d636d7 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -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