openapi: '3.0.2'
info:
  title: Image Management API
  version: 'dev'
servers:
  - url: http://127.0.0.1:8080/
components:
  schemas:
    BuildStatus:
      type: object
      properties:
        build_status:
          type: string
          description: Status that a build is currently in
          enum: [FAILURE, SUCCESS, NOT STARTED, BUILDING]
        name:
          type: string
        download_uuid:
          type: string
          description: Unique, non guessable identifier for the download location, base16 encoded
          example: 11b972aa41e7f08ff1cee7287aace21c1afc17ebeb8a2fb10363090f5be6eed8
        stdout:
          type: string
          description: Output of stdout that the build generated
        stderr:
          type: string
          description: Output of stderr that the build generated
      required:
        - name
        - build_status
    BuildTask:
      type: object
      properties:
        download_handle:
          type: string
          description: Relative URL of the Recipe or tarball to download
          example: /downloads/imageABC.recipe
        key:
          type: string
          description: Base64 representation of the key that the container should be signed with (DRAFT)
        uuid:
          type: string
          description: Unique, non guessable identifier for the API, base16 encoded
      required:
        - download_handle

    Image:
      type: object
      properties:
        path:
          type: string
          description: Absolute Path, where the container image is stored
          example: /p/fastdata/singularity/centos.sif
        recipe_name:
          type: string
          description: Name of the recipe that the container was built on.
          example: CentOS Basic Image
        managed:
          type: boolean
          description: Whether the container is managed and automatically built by the Image DB
          example: false
        download_uuid:
          type: string
          description: Unique, non guessable identifier for the download location, base16 encoded
          example: 11b972aa41e7f08ff1cee7287aace21c1afc17ebeb8a2fb10363090f5be6eed8
        recipe_uuid:
          type: string
          description: Unique, non guessable identifier to request a build, base16 encoded
          example: 92617849533f7d20168a444794f666556e973923681c054597bddb041a721b7d
      required:
        - image_name
        - managed
#  securitySchemes:
#    bearerAuth:
#      type: http
#      scheme: bearer
#      bearerFormat: JWT
#  responses:
#    UnauthorizedError:
#      description: Access token is missing or invalid


    # NewImage:
    #   properties:
    #     file_type:
    #       type: string
    #       enum: [docker, singularity]
    #       required:


paths:
  /images:
    get:
      summary: Returns a list of Images [Not active on production]
      tags:
        - images
      description: Returns all images that are available
      parameters:
        - name: image_name
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of Images available
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Image'

        '404':
          description: There were no Images found that satisfy criterias
    post:
      summary: Import custom image
      tags:
        - images
      description: Import a new custom image into the image database [Not active on production]
      requestBody:
        description: Image that is imported, TODO Authentication of this
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file_type:
                  type: string
                  enum: [oci, sif]
                  description: Type of the image file that is imported, currently unused
                file:
                  type: string
                  format: binary
                  description: Container Image that is uploaded
                image_name:
                  type: string
                  description: Name of the image
              required:
                - file
                - image_name
      responses:
        '201':
          description: The image got successfully imported into the database, metadata is sent back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '400':
          description: An error occured. Most likely this will be an invalid file type

  /images/{recipe_uuid}:
    get:
      tags:
        - images
      summary: Returns the requested image
      description: Returns the image that is requested with the certain recipe UUID
      parameters:
        - name: recipe_uuid
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A specific image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '404':
          description: There was no Image found with the given ID
  /recipes:
    get:
      tags:
       - recipes
      summary: Get all recipes [Not active on production]
      description: Get all the recipes that are available in the image database. This will only include managed recipes and not leave out recipes that have not been built yet.
      parameters:
        - name: recipe_name
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A JSON array of Recipes available
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Image'

        '404':
          description: There were no Images found that satisfy criterias

    post:
      tags:
       - recipes
      summary: Submit new recipe
      description: Submit a new recipe into the image database, can be built by image database
      requestBody:
        description: Recipe that is submitted
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Recipe that is uploaded
                recipe_name:
                  type: string
                  description: Name of the (newly to create) recipe
                image_name:
                  type: string
                  description: Name of the image that the recipe is based on
              required:
                - file
                - recipe_name
      responses:
        '201':
          description: Recipe got imported successfully
        '400':
          description: Import of Recipe failed
        '409':
          description: Recipe is already present in the database. The present Recipe will be sent within the response
  /recipes/content/{recipe_uuid}:
    get:
      tags:
        - recipes
      summary: Get the Recipe file content
      description: Get the Recipe file that is used for the singularity build
      parameters:
        - name: recipe_uuid
          in: path
          description: UUID of the recipe
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Content of the Recipe within the database
        '404':
          description: No Recipe with certain uuid found


  /recipes/{recipe_uuid}:
    put:
      tags:
        - recipes
      summary: Update existing recipe
      description: Update an existing recipe with an updated version that can be built by the image database
      parameters:
        - name: recipe_uuid
          in: path
          description: ID of the recipe that is updated
          required: true
          schema:
            type: integer
      requestBody:
        description: Recipe that is submitted
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Recipe that is uploaded
                image_name:
                  type: string
                  description: Name of the image that the recipe is based on
              required:
                - file
      responses:
        '201':
          description: Recipe got updated successfully
        '400':
          description: Update of Recipe failed
        '409':
          description: Recipe is already present in the database. The present Recipe will be sent within the response
    delete:
      tags:
        - recipes
      summary: Delete existing recipe
      description: Delete an existing recipe from the database. This will delete all references to that recipe
        from the database as well as all files associated.
      parameters:
        - name: recipe_uuid
          in: path
          description: ID of the recipe that is updated
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Recipe got deleted successfully
        '400':
          description: Deletion failed
        '404':
          description: Recipe with given UUID was not found on the server

  /downloads/{download_uuid}:
    get:
      tags:
        - downloads
      summary: Download an Image
      description: Download an Image that got built
      parameters:
        - name: download_uuid
          in: path
          description: UUID of the download handle for the container
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Image with UUID was found and can be downloaded
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Image with UUID was not found
  /build/request/{recipe_uuid}:
    post:
      tags:
        - build
      summary: Request the Build of an Image from an existing Recipe
      description: Build an Image from a Recipe. The Recipe needs to be submitted already
      parameters:
        - name: recipe_uuid
          in: path
          description: UUID of the Recipe for the container
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Build requested
        '404':
          description: Recipe with UUID was not found
        '400':
          description: Build order was already placed
    get:
      tags:
        - build
      summary: Get the status of a certain build request
      description: Get the status of a build request that got placed. If no build request has been placed, this is traceable.
      parameters:
        - name: recipe_uuid
          in: path
          description: UUID of the Recipe for the container
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns Build status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildStatus'

        '404':
          description: Recipe with UUID was not found


