openapi: "3.0.3"
info:
  title: bf_backend
  version: "0.8.32"
servers:
  - url: https://prod-server-01.bugflows.com
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    DemoStatusTrainingResponse:
      type: object
      properties:
        training_job_id:
          type: string
        is_anon:
          type: boolean
        is_model_expired:
          type: boolean
        result:
          $ref: "#/components/schemas/JobResult"
      required:
        - result
        - training_job_id
        - is_anon
        - is_model_expired
    JobResult:
      type: object
      properties:
        status:
          $ref: "#/components/schemas/JobStatus"
        status_description:
          type: string
        error:
          $ref: "#/components/schemas/JobError"
      required:
        - status
        - status_description
    JobStatus:
      type: string
      enum:
        - Success
        - Failed
        - Processing
        - Queued
    JobError:
      type: object
      properties:
        error_type:
          $ref: "#/components/schemas/JobErrorType"
        error_description:
          type: string
      required:
        - error_type
        - error_description
    JobErrorType:
      type: string
      enum:
        - UserError
        - BackendMLError
        - BackendError
        - BackendJobError
    DemoStatusPredictionResponse:
      type: object
      properties:
        prediction_job_id:
          type: string
        is_anon:
          type: boolean
        result:
          $ref: "#/components/schemas/JobResult"
        result_body:
          $ref: "#/components/schemas/PredictionBody"
        similar_issues:
          $ref: "#/components/schemas/SimilarIssues"
      required:
        - result
        - prediction_job_id
        - is_anon
    FinishTrainingRequest:
      type: object
      properties:
        training_job_id:
          type: string
        result:
          $ref: "#/components/schemas/FinishResult"
      required:
        - result
        - training_job_id
    FinishResult:
      type: object
      properties:
        token:
          type: string
        status:
          $ref: "#/components/schemas/FinishStatus"
        status_description:
          type: string
        error:
          $ref: "#/components/schemas/JobError"
      required:
        - token
        - status
        - status_description
    FinishStatus:
      type: string
      enum:
        - Success
        - Failed
    FinishPredictionRequest:
      type: object
      properties:
        prediction_job_id:
          type: string
        result:
          $ref: "#/components/schemas/FinishResult"
        result_body:
          $ref: "#/components/schemas/PredictionBody"
        similar_issues:
          $ref: "#/components/schemas/SimilarIssues"
      required:
        - result
        - prediction_job_id
        - similar_issues
    PredictionBody:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          prediction:
            type: string
          confidence:
            type: number
            format: double
        required:
          - prediction
          - confidence
    SimilarIssues:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          #url:
          #  type: string

paths:
  /:
    get:
      responses:
        "200":
          description: OK
  /verify_email_and_generate_otp:
    post:
      description: "OTP generation API, 6 digit string will be sent to the user's email address and otp will be valid for 10 minutes"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: "User's email address"
              required:
                - email
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  wait_duration_seconds:
                    type: integer
                    format: int32
                    description: "Number of seconds to wait before generating a new OTP"
                required:
                  - wait_duration_seconds
        "400":
          description: Invalid Email address
        "403":
          description: User is on cooldown from a lot of OTP requests
        "429":
          description: OTP generated very recently
          content:
            text/json:
              schema:
                type: object
                properties:
                  remaining_duration_seconds:
                    type: integer
                    format: int32
                    description: "Number of seconds to wait before generating a new OTP"
        "500":
          description: Internal Server Error

  /signin:
    post:
      description: "Signin API"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: "User's email address"
                otp:
                  type: string
                  description: "User's OTP"
              required:
                - email
                - otp
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                    description: "A unique session ID token generated for the user, this session ID is used to do bearer authentication for subsequent frontend APIs, it also defines what user is signed in and performing requests"
                  demo_training_job_status:
                    description: "The status of the last demo training job ID, if any"
                    $ref: "#/components/schemas/DemoStatusTrainingResponse"
                  demo_prediction_job_status:
                    description: "The status of the last demo prediction job ID, if any"
                    $ref: "#/components/schemas/DemoStatusPredictionResponse"
                required:
                  - session_id
        "400":
          description: Invalid email
        "401":
          description: Invalid OTP for this email
        "403":
          description: OTP not generated first, siginin called directly
        "410":
          description: OTP expired
        "500":
          description: Internal Server Error

  /verify_session:
    post:
      description: "Verify if a session ID is valid, return expiry time if true"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                session_id:
                  type: string
                  description: "Session ID Token to be verified"
              required:
                - session_id
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_valid:
                    type: boolean
                    description: "Whether the session ID is valid or not"
                  expires_at_in_seconds_since_epoch:
                    type: integer
                    format: int64
                    description: "The expiry time of the session ID in seconds since epoch"
                required:
                  - is_valid
        "500":
          description: Internal Server Error
  /demo_train:
    post:
      description: "Trains an ML model for a demo user, currently only accepts csv files in form body"
      security:
        - bearerAuth: []
      parameters:
        - in: header
          name: "is_anon"
          description: "Whether the user's model attributes are anonymised or not"
          schema:
            type: boolean
          required: true
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    format: binary
                    description: "User's input csv"
              required:
                - name
              description: "List of user csvs containing Issue data"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  training_job_id:
                    type: string
                    description: "A unique job ID generated by the backend to denote that the server has accepted the request and this job id represents this job which can be used to check status or be used in further APIs"
                required:
                  - training_job_id
        "400":
          description: Bad Request, the provided data is invalid or has inconsistencies and cannot be processed or the provided file type is invalid
        "429":
          description: One training job already running for the user, or max training job limit has been reached or max daily limit is reached, denoted through headers. First the total limit is checked, then the daily limit, then the concurrency limit.
          headers:
            X-TotalLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of training jobs allowed in total"
            X-TotalLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of training jobs allowed in total for this user"
            X-DailyLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of training jobs allowed per day"
            X-DailyLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of training jobs allowed per day for this user"
            X-ConcurrencyLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of concurrent training jobs allowed"
            X-ConcurrencyLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of concurrent training jobs allowed for this user"
        "500":
          description: Internal Server Error
        "503":
          description: No available ml backend to handle the training request or all ml backends are at capacity
  /demo_predict:
    post:
      description: "Predicts data based on user's provided request string and a job id of an already trained job"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json::
            schema:
              type: object
              properties:
                request_string:
                  type: string
                  description: "User's string which will be used to predict the data"
                training_job_id:
                  type: string
                  description: "The job ID of an already trained job that was done by this user"
              required:
                - training_job_id
                - request_string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  prediction_job_id:
                    type: string
                    description: "The job ID of the prediction job"
                required:
                  - prediction_job_id
        "400":
          description: Bad Request, the provided request string either doesn't exist or cannot be processed or the demo training ID could not be found or is invalid or is not finished yet
        "403":
          description: User doesn't have access to this job ID or this job ID has no user that can access it
        "410":
          description: The GCP bucket associated with the user has expired
        "429":
          description: One prediction job already running for the user, or max prediction job limit has been reached or max daily limit is reached, denoted through headers. First the total limit is checked, then the daily limit, then the concurrency limit.
          headers:
            X-TotalLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of prediction jobs allowed in total"
            X-TotalLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of prediction jobs allowed in total for this user"
            X-DailyLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of prediction jobs allowed per day"
            X-DailyLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of prediction jobs allowed per day for this user"
            X-ConcurrencyLimit-Max:
              schema:
                type: integer
                format: int32
              description: "Maximum number of concurrent prediction jobs allowed"
            X-ConcurrencyLimit-Remaining:
              schema:
                type: integer
                format: int32
              description: "Remaining number of concurrent prediction jobs allowed for this user"
        "500":
          description: Internal Server Error
        "503":
          description: No available ml backend to handle the prediction request or all ml backends are at capacity

  /demo_status_training:
    post:
      description: "Status for a training job, given a training job id"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json::
            schema:
              type: object
              properties:
                training_job_id:
                  type: string
                  description: "The job ID of the training job"
              required:
                - training_job_id
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DemoStatusTrainingResponse"
        "400":
          description: Bad Request, the provided  demo training ID could not be found or is invalid or doesn't exist
        "403":
          description: User doesn't have access to this job ID, or this job ID doesn't have a user associated with it
        "500":
          description: Internal Server Error

  /demo_status_prediction:
    post:
      description: "Status for a prediction job, given a prediction job id"
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json::
            schema:
              type: object
              properties:
                prediction_job_id:
                  type: string
                  description: "The job ID of the prediction job"
              required:
                - prediction_job_id
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DemoStatusPredictionResponse"
        "400":
          description: Bad Request, the provided demo training ID could not be found or is invalid or doesn't exist
        "403":
          description: Unauthorized, this user doesn't have access to this job ID
        "500":
          description: Internal Server Error

  /finish_training:
    post:
      description: "Finishes a training job's state in the backend"
      requestBody:
        required: true
        content:
          application/json::
            schema:
              $ref: "#/components/schemas/FinishTrainingRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request, cannot find the training job ID in the active queue, or the provided request body is either invalid or cannot be processed
        "401":
          description: Unauthorized, Token is invalid
        "500":
          description: Internal Server Error
  /finish_prediction:
    post:
      description: "Finishes a prediction job's state in the backend"
      requestBody:
        required: true
        content:
          application/json::
            schema:
              $ref: "#/components/schemas/FinishPredictionRequest"
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request, cannot find the prediction Job ID in active queue, the provided request body is either invalid or cannot be processed
        "401":
          description: Unauthorized, Token is invalid
        "500":
          description: Internal Server Error