From 07ffaf70c0240dee063413f86f9b4f49e0b2c8e0 Mon Sep 17 00:00:00 2001
From: Ismail Mohammed <ism5701@gmail.com>
Date: Fri, 31 May 2024 01:37:37 +0300
Subject: [PATCH 1/3] Updated API documentation for software-catelog

Signed-off-by: Ismail Mohammed <ism5701@gmail.com>
---
 docs/features/software-catalog/api.md | 280 +++++++++++++++++++++++++-
 1 file changed, 279 insertions(+), 1 deletion(-)

diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index d002b12015..2f768a7ef4 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -425,6 +425,10 @@ 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.
 
+### `GET /entities/by-name/{kind}/{namespace}/{name}/ancestry`
+
+Get an entity's ancestry by entity ref.
+
 ### `POST /entities/by-refs`
 
 Gets a batch of entities by their entity refs. This is useful in contexts where
@@ -456,6 +460,35 @@ 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.
 
+### `POST /refresh`
+
+Refresh the entity related to `entityRef`.
+
+Request body is JSON, on the form
+
+```json
+{
+  "entityRef": "<string>",
+  "authorizationToken": "<string>"
+}
+```
+
+### `POST /validate-entity`
+
+Validate that a passed in entity has no errors in schema.
+
+Request body is JSON, on the form
+
+```json
+{
+  "location": "<string>",
+  "entity": {
+    "proident_f": {},
+    "culpa_ca": {}
+  }
+}
+```
+
 ## Locations
 
 ### `GET /locations`
@@ -504,6 +537,39 @@ Response type is JSON, on the form
 }
 ```
 
+### `GET /entity-facets?facet=<string>&facet=<string>&filter=<string>&filter=<string>`
+
+Get all entity facets that match the given filters.
+
+Response type is JSON, on the form
+
+```json
+{
+  "facets": {
+    "exercitation84": [
+      {
+        "value": "<string>",
+        "count": "<number>"
+      },
+      {
+        "value": "<string>",
+        "count": "<number>"
+      }
+    ],
+    "consectetur_1": [
+      {
+        "value": "<string>",
+        "count": "<number>"
+      },
+      {
+        "value": "<string>",
+        "count": "<number>"
+      }
+    ]
+  }
+}
+```
+
 ### `POST /locations`
 
 Adds a location to be ingested by the catalog.
@@ -542,7 +608,219 @@ If the location already exists the response will be `HTTP/1.1 409 Conflict` and
 
 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>`
+### `POST /analyze-location`
+
+Validate a given location.
+
+Request body is JSON, on the form
+
+```json
+{
+  "location": {
+    "type": "<string>",
+    "target": "<string>"
+  },
+  "catalogFileName": "<string>"
+}
+```
+
+And Response type is JSON, on the form
+
+```json
+{
+  "generateEntities": [
+    {
+      "fields": [
+        {
+          "description": "<string>",
+          "value": "<string>",
+          "state": "needsUserInput",
+          "field": "<string>"
+        },
+        {
+          "description": "<string>",
+          "value": "<string>",
+          "state": "analysisSuggestedNoValue",
+          "field": "<string>"
+        }
+      ],
+      "entity": {
+        "apiVersion": "<string>",
+        "kind": "<string>",
+        "metadata": {},
+        "spec": {
+          "ullamco_b24": {}
+        },
+        "relations": [
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          },
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          }
+        ]
+      }
+    },
+    {
+      "fields": [
+        {
+          "description": "<string>",
+          "value": "<string>",
+          "state": "needsUserInput",
+          "field": "<string>"
+        },
+        {
+          "description": "<string>",
+          "value": "<string>",
+          "state": "analysisSuggestedValue",
+          "field": "<string>"
+        }
+      ],
+      "entity": {
+        "apiVersion": "<string>",
+        "kind": "<string>",
+        "metadata": {},
+        "spec": {
+          "velita": {},
+          "aliquip_d": {},
+          "officia__e8": {}
+        },
+        "relations": [
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          },
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          }
+        ]
+      }
+    }
+  ],
+  "existingEntityFiles": [
+    {
+      "entity": {
+        "metadata": {
+          "name": "<string>",
+          "links": [
+            {
+              "url": "<string>",
+              "type": "<string>",
+              "icon": "<string>",
+              "title": "<string>"
+            },
+            {
+              "url": "<string>",
+              "type": "<string>",
+              "icon": "<string>",
+              "title": "<string>"
+            }
+          ],
+          "tags": ["<string>", "<string>"],
+          "annotations": {
+            "nostrud__": "<string>",
+            "ipsumd": "<string>",
+            "amet_bc2": "<string>"
+          },
+          "labels": {
+            "ea1c": "<string>"
+          },
+          "description": "<string>",
+          "title": "<string>",
+          "namespace": "<string>",
+          "etag": "<string>",
+          "uid": "<string>"
+        },
+        "kind": "<string>",
+        "apiVersion": "<string>",
+        "relations": [
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          },
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          }
+        ],
+        "spec": {
+          "culpa982": {},
+          "dolorb": {},
+          "mollitb7e": {}
+        }
+      },
+      "isRegistered": "<boolean>",
+      "location": {
+        "target": "<string>",
+        "type": "<string>"
+      }
+    },
+    {
+      "entity": {
+        "metadata": {
+          "name": "<string>",
+          "links": [
+            {
+              "url": "<string>",
+              "type": "<string>",
+              "icon": "<string>",
+              "title": "<string>"
+            },
+            {
+              "url": "<string>",
+              "type": "<string>",
+              "icon": "<string>",
+              "title": "<string>"
+            }
+          ],
+          "tags": ["<string>", "<string>"],
+          "annotations": {
+            "sint_69": "<string>",
+            "ex5b7": "<string>"
+          },
+          "labels": {
+            "proidentc1": "<string>",
+            "ullamco_c": "<string>",
+            "do_8": "<string>"
+          },
+          "description": "<string>",
+          "title": "<string>",
+          "namespace": "<string>",
+          "etag": "<string>",
+          "uid": "<string>"
+        },
+        "kind": "<string>",
+        "apiVersion": "<string>",
+        "relations": [
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          },
+          {
+            "targetRef": "<string>",
+            "type": "<string>"
+          }
+        ],
+        "spec": {
+          "ine": {},
+          "Ute1": {},
+          "fugiat80": {}
+        }
+      },
+      "isRegistered": "<boolean>",
+      "location": {
+        "target": "<string>",
+        "type": "<string>"
+      }
+    }
+  ]
+}
+```
+
+### `DELETE /locations/{id}`
 
 Delete a location by its id. On success response code will be `HTTP/1.1 204 No Content`.
 

From 9b6210308878c3f59fd969e8d9d558298010500c Mon Sep 17 00:00:00 2001
From: Ismail Mohammed <ism5701@gmail.com>
Date: Sun, 2 Jun 2024 00:26:12 +0300
Subject: [PATCH 2/3] Cleaned code. Removed reduntant sample data

Signed-off-by: Ismail Mohammed <ism5701@gmail.com>
---
 docs/features/software-catalog/api.md | 192 +-------------------------
 1 file changed, 4 insertions(+), 188 deletions(-)

diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index 2f768a7ef4..36b9e96220 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -482,10 +482,7 @@ Request body is JSON, on the form
 ```json
 {
   "location": "<string>",
-  "entity": {
-    "proident_f": {},
-    "culpa_ca": {}
-  }
+  "entity": "<Entity>"
 }
 ```
 
@@ -545,28 +542,7 @@ Response type is JSON, on the form
 
 ```json
 {
-  "facets": {
-    "exercitation84": [
-      {
-        "value": "<string>",
-        "count": "<number>"
-      },
-      {
-        "value": "<string>",
-        "count": "<number>"
-      }
-    ],
-    "consectetur_1": [
-      {
-        "value": "<string>",
-        "count": "<number>"
-      },
-      {
-        "value": "<string>",
-        "count": "<number>"
-      }
-    ]
-  }
+  "facets": "<EntityFacet>"
 }
 ```
 
@@ -644,172 +620,12 @@ And Response type is JSON, on the form
           "field": "<string>"
         }
       ],
-      "entity": {
-        "apiVersion": "<string>",
-        "kind": "<string>",
-        "metadata": {},
-        "spec": {
-          "ullamco_b24": {}
-        },
-        "relations": [
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          },
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          }
-        ]
-      }
-    },
-    {
-      "fields": [
-        {
-          "description": "<string>",
-          "value": "<string>",
-          "state": "needsUserInput",
-          "field": "<string>"
-        },
-        {
-          "description": "<string>",
-          "value": "<string>",
-          "state": "analysisSuggestedValue",
-          "field": "<string>"
-        }
-      ],
-      "entity": {
-        "apiVersion": "<string>",
-        "kind": "<string>",
-        "metadata": {},
-        "spec": {
-          "velita": {},
-          "aliquip_d": {},
-          "officia__e8": {}
-        },
-        "relations": [
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          },
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          }
-        ]
-      }
+      "entity": "<Entity>"
     }
   ],
   "existingEntityFiles": [
     {
-      "entity": {
-        "metadata": {
-          "name": "<string>",
-          "links": [
-            {
-              "url": "<string>",
-              "type": "<string>",
-              "icon": "<string>",
-              "title": "<string>"
-            },
-            {
-              "url": "<string>",
-              "type": "<string>",
-              "icon": "<string>",
-              "title": "<string>"
-            }
-          ],
-          "tags": ["<string>", "<string>"],
-          "annotations": {
-            "nostrud__": "<string>",
-            "ipsumd": "<string>",
-            "amet_bc2": "<string>"
-          },
-          "labels": {
-            "ea1c": "<string>"
-          },
-          "description": "<string>",
-          "title": "<string>",
-          "namespace": "<string>",
-          "etag": "<string>",
-          "uid": "<string>"
-        },
-        "kind": "<string>",
-        "apiVersion": "<string>",
-        "relations": [
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          },
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          }
-        ],
-        "spec": {
-          "culpa982": {},
-          "dolorb": {},
-          "mollitb7e": {}
-        }
-      },
-      "isRegistered": "<boolean>",
-      "location": {
-        "target": "<string>",
-        "type": "<string>"
-      }
-    },
-    {
-      "entity": {
-        "metadata": {
-          "name": "<string>",
-          "links": [
-            {
-              "url": "<string>",
-              "type": "<string>",
-              "icon": "<string>",
-              "title": "<string>"
-            },
-            {
-              "url": "<string>",
-              "type": "<string>",
-              "icon": "<string>",
-              "title": "<string>"
-            }
-          ],
-          "tags": ["<string>", "<string>"],
-          "annotations": {
-            "sint_69": "<string>",
-            "ex5b7": "<string>"
-          },
-          "labels": {
-            "proidentc1": "<string>",
-            "ullamco_c": "<string>",
-            "do_8": "<string>"
-          },
-          "description": "<string>",
-          "title": "<string>",
-          "namespace": "<string>",
-          "etag": "<string>",
-          "uid": "<string>"
-        },
-        "kind": "<string>",
-        "apiVersion": "<string>",
-        "relations": [
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          },
-          {
-            "targetRef": "<string>",
-            "type": "<string>"
-          }
-        ],
-        "spec": {
-          "ine": {},
-          "Ute1": {},
-          "fugiat80": {}
-        }
-      },
+      "entity": "<Entity>",
       "isRegistered": "<boolean>",
       "location": {
         "target": "<string>",

From 92be25ef2769581d666add4be30648602761bf11 Mon Sep 17 00:00:00 2001
From: Ismail Mohammed <ism5701@gmail.com>
Date: Fri, 7 Jun 2024 01:00:57 +0300
Subject: [PATCH 3/3] Corrected types

Signed-off-by: Ismail Mohammed <ism5701@gmail.com>
---
 docs/features/software-catalog/api.md | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/features/software-catalog/api.md b/docs/features/software-catalog/api.md
index 36b9e96220..ec699d2760 100644
--- a/docs/features/software-catalog/api.md
+++ b/docs/features/software-catalog/api.md
@@ -468,8 +468,7 @@ Request body is JSON, on the form
 
 ```json
 {
-  "entityRef": "<string>",
-  "authorizationToken": "<string>"
+  "entityRef": "<string>"
 }
 ```
 
@@ -482,7 +481,7 @@ Request body is JSON, on the form
 ```json
 {
   "location": "<string>",
-  "entity": "<Entity>"
+  "entity": {}
 }
 ```
 
@@ -542,7 +541,12 @@ Response type is JSON, on the form
 
 ```json
 {
-  "facets": "<EntityFacet>"
+  "facets": [
+    {
+      "value": "<string>",
+      "count": 1
+    }
+  ]
 }
 ```
 
@@ -615,12 +619,12 @@ And Response type is JSON, on the form
         },
         {
           "description": "<string>",
-          "value": "<string>",
+          "value": {},
           "state": "analysisSuggestedNoValue",
           "field": "<string>"
         }
       ],
-      "entity": "<Entity>"
+      "entity": {}
     }
   ],
   "existingEntityFiles": [