From d1aa79a20e66009358e1f0f938977d8a003372c7 Mon Sep 17 00:00:00 2001
From: Rickard Dybeck <dybeck@spotify.com>
Date: Tue, 29 Aug 2023 09:26:56 -0400
Subject: [PATCH] [catalog] Update api documentation (#19520)

* [catalog] Update api documentation

Update catalog api documentation for location endpoint.

Signed-off-by: Rickard Dybeck <dybeck@spotify.com>
---
 docs/features/software-catalog/api.md | 60 ++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)

diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index 3ca7e5ef49..3ccd89b286 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -279,7 +279,65 @@ where the `items` array has _the same length_ and _the same order_ as the input
 
 ## Locations
 
-TODO
+### `GET /locations`
+
+Lists locations.
+
+Response type is JSON, on the form
+
+```json
+[
+  {
+    "data": {
+      "id": "b9784c38-7118-472f-9e22-5638fc73bab0",
+      "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",
+      "type": "url"
+    }
+  }
+]
+```
+
+### `POST /locations`
+
+Adds a location to be ingested by the catalog.
+
+If successful the response code will be `HTTP/1.1 201 Created` and a JSON on the form
+
+```json
+{
+  "entities": [],
+  "location": {
+    "id": "b9784c38-7118-472f-9e22-5638fc73bab0",
+    "target": "https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml",
+    "type": "url"
+  }
+}
+```
+
+If the location already exists the response will be `HTTP/1.1 409 Conflict` and a JSON on the form
+
+```json
+{
+  "error": {
+    "message": "Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists",
+    "name": "ConflictError",
+    "stack": "ConflictError: Location url:https://git.example.com/example-project/example-repository/blob/main/catalog-info.yaml already exists\n..."
+  },
+  "request": {
+    "method": "POST",
+    "url": "/locations"
+  },
+  "response": {
+    "statusCode": 409
+  }
+}
+```
+
+Supports the `?dryRun=true` query parameter, which will perform validation and not write anything to the database. In the event of successfully passing validation, the `entities` field of the response JSON will be populated with entities present in the location.
+
+### `DELETE /locations/<uid>`
+
+Delete a location by its id. On success response code will be `HTTP/1.1 204 No Content`.
 
 ## Other