diff --git a/README.md b/README.md index b83696bc0b8da5b697314112fbb0801f0091f624..60f342c11125e79b389340edc59537b8629f86e9 100644 --- a/README.md +++ b/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. | diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 3c62621d4e79f944b6556377ba64340b7565b1af..2e921ffc76e442a72f00994f592e156dfe9b535f 100644 --- a/spec/openapi.yaml +++ b/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