---
openapi: 3.0.3
info:
  title: Humio Package Registry API
  description: A service for distributing Humio packages.
  termsOfService: http://humio.com/terms-and-conditions/
  contact:
    name: Humio Support
    url: http://www.humio.com/support
    email: logscalesupport@crowdstrike.com
  license:
    name: Apache 2.0
    url: https://github.com/OAI/OpenAPI-Specification/blob/master/https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

paths:
  /packages:
    get:
      parameters:
        - name: search
          in: query
          description: Text to search for packages with
          required: false
          schema:
            type: string
        - name: categories
          in: query
          description: Include only packages with all of these categories
          required: false
          schema:
            type: array
            items:
              type: string
        - name: tags
          in: query
          description: The tags to find packages for (not currently supported)
          required: false
          schema:
            type: array
            items:
              type: string
        - name: preferredCompatibleHumioVersion
          in: query
          description: The version of humio that package returned needs to be compatible with if possible. If no versions are compatible, the most recent version is included
          required: false
          schema:
            type: string

      operationId: listPackages
      summary: List available packages
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PackageInfoList"
        '500':
          description: Internal Server Error

  /packages/{scope}:
    parameters:
      - name: scope
        in: path
        description: The scope of the package
        required: true
        schema:
          type: string
    get:
      operationId: getPackagesInScope
      summary: Gets the packages with a certain scope
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PackageInfoList"
        '404':
          description: Not Found
        '400':
          description: Invalid
        '500':
          description: Internal Server Error

  /packages/{scope}/{packageName}/versions:
    parameters:
      - name: scope
        in: path
        description: The scope of the package
        required: true
        schema:
          type: string
      - name: packageName
        in: path
        description: The name of the package
        required: true
        schema:
          type: string
    get:
      operationId: getPackageVersions
      summary: Lists all available versions of a package.
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionInfo'
        '404':
          description: Not Found
        '400':
          description: Invalid
        '500':
          description: Internal Server Error


  /categories:
    get:
      operationId: getCategories
      summary: List the items in a
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/CategoryList"


  /packages/{scope}/{packageName}:
    parameters:
      - name: scope
        in: path
        description: The scope of the package
        required: true
        schema:
          type: string
      - name: packageName
        in: path
        description: The name of the package
        required: true
        schema:
          type: string
    get:
      operationId: getLatestPackageInfo
      summary: Gets the data for the latest version of this package
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/LatestPackageInfo"
        '404':
          description: Not Found
        '400':
          description: Invalid
        '410':
          description: All versions of the package are unpublished
        '500':
          description: Internal Server Error

  /packages/{scope}/{packageName}/{version}:
    parameters:
      - name: scope
        in: path
        description: The scope of the package
        required: true
        schema:
          type: string
      - name: packageName
        in: path
        description: The name of the package
        required: true
        schema:
          type: string
      - name: version
        in: path
        description: The version of the package
        required: true
        schema:
          type: string
    get:
      operationId: getPackageInfo
      summary: Gets data about a package
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/PackageInfo"
        '404':
          description: Not Found
        '400':
          description: Invalid
        '410':
          description: Unpublished
        '500':
          description: Internal Server Error

  /packages/{scope}/{packageName}/{version}/download:
    parameters:
      - name: scope
        in: path
        description: The scope of the package
        required: true
        schema:
          type: string
      - name: packageName
        in: path
        description: The name of the package
        required: true
        schema:
          type: string
      - name: version
        in: path
        description: The version of the package
        required: true
        schema:
          type: string
    get:
      operationId: downloadPackage
      summary: Downloads a package
      x-server-raw-response: true
      responses:
        '307':
          description: Redirect to download URL
          headers:
            X-Location:
              schema:
                type: string
              description: Url which must be used to download the package. Guaranteed to always be absolute.
        '404':
          description: Not Found
        '400':
          description: Invalid
        '410':
          description: Unpublished
        '500':
          description: Internal Server Error



components:
  schemas:
    CategoryList:
      type: object
      required:
        - groups
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/CategoryGroup"

    CategoryGroup:
      type: object
      required:
        - title
        - categories
      properties:
        title:
          type: string
        categories:
          type: array
          items:
            $ref: "#/components/schemas/Category"

    Category:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: string
        title:
          type: string


    LatestPackageInfo:
      type: object
      properties:
        latestPackage:
          $ref: "#/components/schemas/PackageInfo"
        otherVersions:
          type: array
          deprecated: true
          items:
            type: string
      required:
        - latestPackage
        - otherVersions

    PackageInfo:
      type: object
      properties:
        specifier:
          $ref: '#/components/schemas/Specifier'
        description:
          type: string
        author:
          $ref: '#/components/schemas/PackageAuthor'
        logoUrl:
          type: string
        tags:
          type: array
          items:
            type: string
        type:
          type: string
          enum:
            - application
            - library
        minimumHumioVersion:
          type: string
      required:
        - specifier
        - author
        - description
        - type
        - minimumHumioVersion

    PackageAuthor:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name

    PackageInfoList:
      type: object
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/PackageInfo'
      required:
        - packages

    VersionInfo:
      type: object
      properties:
        version:
          type: string
        minHumioVersion:
          type: string
      required:
        - version
        - minHumioVersion

    PackageMetadata:
      type: object
      properties:
        isUnpublished:
          type: boolean
      required:
        - isUnpublished

    Specifier:
      type: object
      properties:
        scope:
          type: string
          example: acmecorp
        name:
          type: string
          example: dashboards
        version:
          type: string
          example: 1.0.0
      required:
        - scope
        - name
        - version