feat: Add reports usage to readme

README.md

@@ -12,14 +12,21 @@ This project uses Quarkus, the Supersonic Subatomic Java Framework.
 If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .
 
 <!-- TOC -->
-- [About validation](#about-validation)
+- [git-eca-rest-api](#git-eca-rest-api)
+  - [About validation](#about-validation)
     - [What is a valid commit?](#what-is-a-valid-commit)
     - [Submitting applications for existing bots](#submitting-applications-for-existing-bots)
     - [Enabling commit hook in GitLab](#enabling-commit-hook-in-gitlab)
-- [Application setup and operation](#application-setup-and-operation)
-    - [Setting up the application](#setting-up-the-application)
+    - [Configure environment](#configure-environment)
+    - [Update your Host file](#update-your-host-file)
+  - [Application setup and operation](#application-setup-and-operation)
+    - [Setting up the application for local use](#setting-up-the-application-for-local-use)
     - [Running the application in dev mode](#running-the-application-in-dev-mode)
     - [Packaging and running the application](#packaging-and-running-the-application)
+  - [Private Project Reports](#private-project-reports)
+    - [Usage](#usage)
+      - [Usage Params](#usage-params)
+      - [Report Schema](#report-schema)
 <!-- /TOC -->
 
 ## About validation
@@ -105,3 +112,31 @@ Be aware that it’s not an _über-jar_ as the dependencies are copied into the
 
 The application is now runnable using `java -jar target/git-eca-rest-api-0.0.1-runner.jar`.
 
+## Private Project Reports
+### Usage
+
+The private project reports are accessed through `/git/reports/gitlab/private-projects` and can be filtered using various parameters.
+
+#### Usage Params
+
+| Parameter name | Required | Accepts | Default | Description |
+|----------------|:--------:|---------|---------|-------------|
+| key | ✓ | string | N/A | The private access token required to use this endpoint  |
+| status | x | string | N/A | The project status. Either 'active' or 'deleted' |
+| since | x | datestamp (ISO 8601), ex: 2022-10-11 | N/A | Starting date stamp for getting a slice of tracked private projects |
+| until | x | datestamp (ISO 8601), ex: 2022-10-11 | N/A | Ending date stamp for getting a slice of tracked private projects |
+
+#### Report Schema
+
+The reports endpoint will return a list of objects with relevant info on tracked private projects.
+The `Volatile` column denotes whether the property is subject to change once initially tracked.
+
+| Property name | Type | Volatile | Description |
+|---------------|------|:--------:|-------------|
+| user_id | integer | x | The project creator's Gitlab userid. |
+| project_id | integer | x | The project's Gitlab id. |
+| project_path | string | ✓ | The project's path with namespace. Subject to change. |
+| ef_username | string | ✓ | The project creator's EF username. Subject to change. |
+| parent_project | integer/null | ✓ | Denotes whether the project has a parent, which indicates a fork. However, the user can remove the relation to the parent project. |
+| creation_date | string | x | The project's creation date. |
+| deletion_date | string/null | ✓ | The project's deletion date. Subject to change. |

spec/openapi.yaml

@@ -47,6 +47,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/CommitValidationStatuses"
+        500:
+          description: Error while retrieving data
 
   /eca/status/{fingerprint}/ui:
     get:
@@ -57,6 +59,8 @@ paths:
           description: Success. An HTML page containing status info
         404:
           description: Not Found
+        500:
+          description: Error while retrieving data
 
   /eca/lookup:
     get:
@@ -69,6 +73,8 @@ paths:
           description: User exists with no ECA
         404:
           description: User not found
+        500:
+          description: Error while retrieving data
 
   /webhooks/gitlab/system:
     post:
@@ -95,6 +101,12 @@ paths:
 
   /reports/gitlab/private-projects:
     parameters:
+      - name: key
+        in: query
+        description: The endpoint access key
+        required: true
+        schema:
+          type: string
       - name: status
         in: query
         description: the project's current status - active/deleted
@@ -132,7 +144,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
         401:
-          description: Unauthorized - user not allowed
+          description: Unauthorized - invalid key
         500:
           description: Error while processing request