openapi: 3.0.3
info:
  title: blek! File (fileD) File API
  description: |-
    This document describes the API of the File API of blek! File fileD.

    This API has optional api key authorization, which should be located in the env file.
  version: 0.0.1
servers:
  - url: http://localhost
    description: Local staging environment
tags:
  - name: File API
    description: API for interacting with files
paths:
  /api/files/get_all:
    get:
      summary: Get all files
      description: |-
        Get all files available.

        Returns an array of file objects with all data
      tags:
        - File API
      security:
        - apikey: [ key ]
      responses:
        200:
          description: An array of file objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
                example:
                  - path: /opt/useruploads/417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a
                    size: 10
                    name: null
                    mime: text/plain
                    delete_at: '1984-01-01T00:00:00.000Z'
                    sha512: 417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a
        401:
          description: |-
            This error code is returned if one of the two conditions are met:

            1. The instance does not allow getting information about all files.
            2. The instance requires API key for all API manipulations.
            3. The provided API key is invalid.
            4. API authorization is not enabled, but a key is provided
  /api/files/delete:
    post:
      summary: Delete a file
      description: |-
        Deletes a file thats been uploaded.

        It will work if one of the two conditions are met:  
        1. The requester's IP is the same as the uploader IP
        2. The request is authorized with an API key
      tags:
        - File API
      security:
        - apikey: [ key ]
      responses:
        200:
          description: |-
            The file has been deleted

            Returns an empty object for future extension
          content:
            application/json:
              schema:
                type: object
                example: {}
        401:
          description: |-
            This error code is returned if one of these conditions are met:

            1. The instance does not allow deleting files via API.
            2. The file has been uploaded from another IP, which is not this one, and the API was not authorized via an API key.
            3. The instance requires API key for all API manipulations.
            4. The provided API key is invalid.
            5. API authorization is not enabled, but a key is provided
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fid:
                  type: string
                  example: ID or name of the file. It is the NAME in file.blek.codes/uploads/NAME
                api_key:
                  type: string
                  example: '123'
  /api/files/upload:
    post:
      summary: Upload a file
      description: |-
        A programmatic way to upload a file.  

        The request must be encoded in `multipart/form-data` to ensure that the binary file is transferred properly.
      tags:
        - File API
      security:
        - apikey: [ key ]
      requestBody:
        description: |-
          A multipart form
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  example: binary file data
                  description: binary file data
                instance_pass:
                  type: string
                  example: super_secret_pass
                  description: Instance-specific password needed to upload files
                metadata:
                  type: object
                  description: |-
                    JSON object with file info:
                    
                    ```
                    {
                      sha512: string,
                      name?: string,
                      pass?: string
                    }
                    ```

                    Note that the content type does not matter on this one.
                  properties:
                    sha512:
                      type: string
                      description: SHA512 hash of the file to ensure integrity
                    name:
                      type: string
                      description: Optional name of the file so it would be accessible like file.blek.codes/uploads/{name}
                    pass:
                      type: string
                      description: Optional password protection for the file
      responses:
        200:
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    example: 'OK'
        401:
          description: |-
            This error code is returned if one of the 4 conditions are met:

            1. The instance does not allow API file uploads.
            2. The instance requires API key for all API manipulations.
            3. The provided API key is invalid.
            4. API authorization is not enabled, but a key is provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    example: 'APIPasswordDenied'
                  details:
                    example: 'API password authorization has been denied.'
        403:
          description: |-
            This error code is returned if your request payload is malformed or the hash doesn't match the file
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    example: 'APIError'
                  details:
                    example: 'Request payload invalid'

components:

  schemas:
    File:
      type: object
      properties:
        path:
          type: string
          description: Path to the file in fileD's filesystem
          example: 1
        size:
          type: integer
          description: Size of the file in bytes
          example: 10
        name:
          type: string
          description: (optional) Name of the file
          example: null
        mime:
          type: string
          description: MIME type of the file
          example: text/plain
        delete_at:
          type: string
          description: TimeDate when the file will be deleted
          example: '1984-01-01T00:00:00.000Z'
        sha512:
          type: string
          example: 417e1ec1a0e82aac809da7e5aa309e03bf47eaa96ab2e335f5bb739d062d835b04ccebb89214bd5a54879527789a81ae4e9deab813e4212c757b36d08fa8165a

  securitySchemes:
    apikey:
      type: http
      scheme: bearer
      description: Optional authorization, as defined in the instance-specific config file