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)

  version: 1.0.1
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
              - built
              - skipped
              - delayed
              - building
              - signing
              - unknown
              - queued
        - name: pkgbase
          in: query
          description: Pkgbase value to filter
          required: false
          schema:
            type: string
        - name: repo
          in: query
          description: Repo to filter
          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"]
        repo:
          type: string
          examples: ["extra-x86-64-v4"]
        split_packages:
          type: array
          items:
            type: string
          examples:
            - ["linux-zen", "linux-zen-headers", "linux-zen-docs"]
        status:
          type: string
          examples: [latest]
          enum:
              - latest
              - failed
              - built
              - skipped
              - delayed
              - building
              - signing
              - unknown
              - queued
        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.
          examples: ["5 GB"]

    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