openapi: 3.1.0
info:
  title: ALHP API
  description: |-
    The ALHP API allows to retrieve package information and general build statistics.

    Useful resources:
    - [ALHP Git Repository](https://somegit.dev/ALHP/ALHP.GO)
    - [ALHP Web Frontend Repository](https://somegit.dev/ALHP/alhp-web)

  version: 1.0.2

servers:
  - url: https://api.alhp.dev

tags:
  - name: package
    description: Endpoints related to package data and metadata
  - name: general
    description: Endpoints providing overall project status and statistics

paths:
  /packages:
    get:
      tags:
        - package
      summary: Retrieve package information
      description: Fetch packages from the ALHP system. You can filter results using query parameters.
      operationId: getPackages
      parameters:
        - name: status
          in: query
          description: Filter by package status. Accepts multiple values via repeated parameters.
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - latest
                - failed
                - built
                - skipped
                - delayed
                - building
                - signing
                - unknown
                - queued
            example: [ "latest", "failed" ]
        - name: pkgbase
          in: query
          description: Filter by the base package name (`pkgbase`). This is often the main identifier of a package group.
          required: false
          schema:
            type: string
            example: "linux-zen"
        - name: exact
          in: query
          description: If present, matches the `pkgbase` exactly. If not provided, allows partial matches.
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: repo
          in: query
          description: Filter by repository name.
          required: false
          schema:
            type: string
            example: "extra-x86-64-v4"
        - name: offset
          in: query
          description: Number of results to skip (for pagination).
          required: true
          schema:
            type: number
            example: 0
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: true
          schema:
            type: number
            example: 25
      responses:
        '200':
          description: Package data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  packages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Package'
                  total:
                    type: integer
                    format: int64
                    description: Total number of matching packages
                    example: 1423
                  offset:
                    type: integer
                    format: int64
                    example: 0
                  limit:
                    type: integer
                    format: int64
                    example: 25
        '404':
          description: No packages found matching the specified filters
        '500':
          description: Internal server error occurred

  /stats:
    get:
      tags:
        - general
      summary: Retrieve general build statistics
      operationId: getStats
      responses:
        '200':
          description: General statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stats'
        '500':
          description: Internal server error occurred

components:
  schemas:
    Package:
      type: object
      properties:
        pkgbase:
          type: string
          description: The base name of the package
          example: "linux-zen"
        repo:
          type: string
          description: Repository from which the package originates
          example: "extra-x86-64-v4"
        split_packages:
          type: array
          description: List of package names split from the base package
          items:
            type: string
          example: [ "linux-zen", "linux-zen-headers", "linux-zen-docs" ]
        status:
          type: string
          description: Current build or repository status of the package
          enum:
            - latest
            - failed
            - built
            - skipped
            - delayed
            - building
            - signing
            - unknown
            - queued
          example: "latest"
        skip_reason:
          type: string
          description: Reason for skipping the package build (if any)
          example: "blacklisted"
        lto:
          type: string
          description: Link Time Optimization (LTO) status for the package
          enum:
            - enabled
            - unknown
            - disabled
            - auto_disabled
          example: "enabled"
        debug_symbols:
          type: string
          description: Availability of debug symbols in the package
          enum:
            - available
            - unknown
            - not_available
          example: "available"
        arch_version:
          type: string
          description: Version available in the official Arch Linux repositories
          example: "1.3.4-2"
        repo_version:
          type: string
          description: Version available in ALHP repositories (may be empty if not built)
          example: "1.3.4-2.1"
        build_date:
          type: string
          description: Date and time when the package was built (RFC1123 format)
          example: "Fri, 15 Dec 2023 03:43:11 UTC"
        peak_mem:
          type: string
          description: Peak memory usage during the build process (human-readable format)
          example: "5 GB"

    Stats:
      type: object
      description: Aggregated statistics across all packages
      properties:
        failed:
          type: integer
          format: int64
          description: Number of packages that failed to build
          example: 17
        skipped:
          type: integer
          format: int64
          description: Number of packages that were skipped
          example: 29
        latest:
          type: integer
          format: int64
          description: Number of packages that are up-to-date
          example: 743
        queued:
          type: integer
          format: int64
          description: Number of packages currently in the build queue
          example: 5
        building:
          type: integer
          format: int64
          description: Number of packages currently building
          example: 11
        last_mirror_timestamp:
          type: integer
          format: int64
          description: Latest mirror timestamp to detect outdated mirrors (Unix timestamp)
          example: 1702612991
        lto:
          type: object
          description: LTO status summary across all packages
          properties:
            enabled:
              type: integer
              format: int64
              description: Number of packages with LTO enabled
              example: 532
            disabled:
              type: integer
              format: int64
              description: Number of packages with LTO explicitly disabled
              example: 203
            unknown:
              type: integer
              format: int64
              description: Number of packages with unknown LTO status
              example: 11