added openapi definition

2023-12-15 18:12:42 +01:00
parent 2a6f5ae26d
commit 1759092b57
2 changed files with 195 additions and 6 deletions
--- a/openapi_alhp.yaml
+++ b/openapi_alhp.yaml
@@ -0,0 +1,189 @@
+openapi: 3.1.0
+info:
+  title: ALHP API
+  description: |-
+    ALHP API used to retrieve information about packages and general statistics.
+
+    Some useful links:
+    - [ALHP Git](https://somegit.dev/ALHP/ALHP.GO)
+    - [ALHP Web Git](https://somegit.dev/ALHP/alhp-web)
+
+  license:
+    name: GPL3
+    url: https://somegit.dev/ALHP/alhp-web/src/branch/main/LICENSE
+  version: 1.0.0
+servers:
+  - url: https://api.alhp.dev
+tags:
+  - name: package
+    description: Everything about packages
+  - name: general
+    description: General information related to overall project status
+paths:
+  /packages:
+    get:
+      tags:
+        - package
+      summary: Get information about packages
+      description: Retrieve packages with or without filtering
+      operationId: getPackages
+      parameters:
+        - name: status
+          in: query
+          description: Status value to filter for
+          required: false
+          schema:
+            type: string
+            enum:
+              - latest
+              - failed
+              - build
+              - skipped
+              - delayed
+              - building
+              - signing
+              - unknown
+        - name: pkgbase
+          in: query
+          description: Pkgbase value to filter for
+          required: false
+          schema:
+            type: string
+        - name: offset
+          in: query
+          description: How many entries to skip
+          required: true
+          schema:
+            type: number
+        - name: limit
+          in: query
+          description: How many entries to return at max
+          required: true
+          schema:
+            type: number
+      responses:
+        '200':
+          description: Successful retrieveal
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: 
+                  packages:
+                    type: array
+                    items: 
+                      $ref: '#/components/schemas/Package'
+                  total:
+                    type: integer
+                    format: int64
+                  offset:
+                    type: integer
+                    format: int64
+                  limit:
+                    type: integer
+                    format: int64
+        '404':
+          description: No packages found matching filters
+        '500':
+          description: Internal error
+  /stats:
+    get:
+      tags:
+        - general
+      summary: Get general package stats
+      operationId: getStats
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Stats'
+        '500':
+          description: Internal error
+  
+components:
+  schemas:
+    Package:
+      type: object
+      properties:
+        pkgbase:
+          type: string
+          examples: ["linux-zen"]
+        split_packages:
+          type: array
+          items:
+            type: string
+          examples: ["linux-zen", "linux-zen-headers", "linux-zen-docs"]
+        status:
+          type: string
+          examples: [latest]
+          enum:
+              - latest
+              - failed
+              - build
+              - skipped
+              - delayed
+              - building
+              - signing
+              - unknown
+        skip_reason:
+          type: string
+          examples: ["blacklisted"]
+        lto:
+          type: string
+          examples: [enabled]
+          enum:
+              - enabled
+              - unknown
+              - disabled
+              - auto_disabled
+        debug_symbols:
+          type: string
+          examples: [available]
+          enum:
+              - available
+              - unknown
+              - not_available
+        arch_version:
+          description: Version alhp compares to from official Archlinux repositories.
+          type: string
+          examples: ["1.3.4-2"]
+        repo_version:
+          description: Version alhp currently offers in its repositories. Can be missing/empty.
+          type: string
+          examples: ["1.3.4-2.1"]
+        build_date:
+          description: When the package was build, formatted after RFC1123
+          type: string
+          examples: ["Fri, 15 Dec 2023 03:43:11 UTC"]
+        peak_mem:
+          description: Peak memory the package used while building. Is formatted in a human readable format.
+
+    Stats:
+      type: object
+      properties:
+        failed:
+          type: integer
+          format: int64
+        skipped:
+          type: integer
+          format: int64
+        latest:
+          type: integer
+          format: int64
+        queued:
+          type: integer
+          format: int64
+        lto:
+          type: object
+          properties: 
+            enabled:
+              type: integer
+              format: int64
+            disabled:
+              type: integer
+              format: int64
+            unknown:
+              type: integer
+              format: int64