openapi: 3.0.0
info:
  title: Saimple Backend API v2
  version: 2.0.0
  description: |
    This page is a specification for the **Saimple** API.

    # Introduction

    ## To test the following routes with the Swagger interface:

      - First, **select the server** which should handle the request. By default, the specification should access the development server.
      - **Acquire an authentication token** using the `POST api/v2/authentification` route, as it is required by most of our API routes. To do that, you'll need to:
          - **Copy** the `access_token` value from the JSON response.
          - **Paste** it in the popup field which appear when clicking the **'Authorise'** button on the right on the page, before the routes descriptions.

    ## Notes:
      - When using a **local stack**, be sure to use the **same IP** for **Swagger** and the **accessed stack** to **avoid CORS issues**.
      - In case you'd want to use the **Curl script**, you may have to add the `--insecure` option to **avoid certificate issues.**
servers:
  - url: https://saimpledev.lan/
  - url: https://{ip}:{port}
    variables:
      ip:
        default: 127.0.0.1
        description: Customer ID assigned by the service provider
      port:
        default: '3087'
tags:
  - name: Evaluations
    description: Evaluations operations
  - name: Dominance
    description: Retrieve dominance information
  - name: Relevance
    description: Retrieve relevance information
  - name: Inputs
    description: Inputs data operations
  - name: Models
    description: Models operations
  - name: Utils
    description: Utility endpoints
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
paths:
  /api/v2/evaluations:
    post:
      tags:
        - Evaluations
      description: |
        ### Allows the launch and creation of an evaluation object

        **Notes:**
          - Returns the created **evaluation's identifier**.
          - This can be used to **track** the evaluation status using the `GET` route.
          - The evaluation status can be : **in progress, done or failed**.
      summary: Create an evaluation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dataType
                - input
                - model
                - name
                - noise
              properties:
                analysisType:
                  default: float
                  description: >-
                    The floating type to use - 'float' being the fastest and
                    less precise & 'float128' or 'quad' being the slowest yet
                    the most precise
                  enum:
                    - float
                    - double
                    - long double
                    - float128 | quad
                  type: string
                dataType:
                  description: >
                    Indicates whether the evaluation will handle Image or
                    TimeSeries data.

                    The image format supported are : *.png, *.jpg, *.jpeg,
                    *.tiff, *.raw "

                    The TimeSeries format supported are :.csv or .npy
                  enum:
                    - Image
                    - TimeSeries
                  type: string
                description:
                  description: Description of the evaluation
                  type: string
                evaluationEngine:
                  default: fae
                  description: The internal evaluation engine to select
                  enum:
                    - fae
                    - fae_ts
                    - ad_svm
                  type: string
                force:
                  description: >-
                    When enabled, the evaluation will ignore most errors or
                    assert
                  default: false
                  type: boolean
                input:
                  description: >-
                    The input data file to use for this evaluation, either its
                    name or its resource identifier
                  type: string
                inputDomain:
                  items:
                    description: >-
                      Given the min/max bound defining the valid domain which
                      must be respected after noise application
                    type: string
                  type: array
                model:
                  description: >-
                    The model to use for this evaluation, either its name or its
                    resource identifier
                  type: string
                name:
                  description: ' The name associated with the evaluation'
                  type: string
                noise:
                  properties:
                    intensitiy:
                      description: >-
                        Value describing the intensity of the the abstract noise
                        applied to the input data
                      type: string
                    mode:
                      description: >-
                        The mode that will be used to create the abstract
                        domain. The mode may induce further parameter
                        requirements. Some parameter are currently hardcoded. If
                        either Bokeh or gaussian is selected, a blur operation
                        is performed on an image which is previously made
                        abstract using the additive noise. Furthermore, some
                        parameters are hardcoded, such as sigma=1.0 and the
                        kernel size = 7x7
                      enum:
                        - NONE
                        - ADDITIVE
                        - MULTIPLICATIVE
                        - BOKEH
                        - GAUSSIAN
                      type: string
                  required:
                    - mode
                    - intensity
                  type: object
                id:
                  default: ''
                  type: string
                  description: >-
                    The evaluation Id. Normaly, should not be given here, as it
                    will be generated
                postProcessing:
                  default: true
                  type: boolean
                  description: >-
                    This flag enable a post processing when the abstraction
                    analysis is finished. Currently it only works for
                    classifier. It should be set to false for other model
                normalize:
                  default: true
                  description: >-
                    When true, normalize from 0-255 to 0-1 - When set to false,
                    use the input data as it is
                  type: boolean
                outputSelected:
                  description: >-
                    The name of the tensor  we want evaluated, can be used for
                    early termination or to get to a point to restart from.
                  type: string
                sanityCheck:
                  description: >-
                    Enable sanity control on the result, checking if the result
                    from a concrete evaluation obtained through onnxruntime are
                    contained in the abstract values obtained through the
                    analysis. Possible values: none(disable), basic(check the
                    final tensor), full(check all tensors after each operations)
                  type: string
                sanityTreshold:
                  description: >-
                    The tolerance value for sanity check. Used as a relative
                    value.
                  type: string
                startAt:
                  description: The layer where to start the analysis from in the model
                  type: string
            examples:
              ImageClassifier:
                value:
                  analysisType: double
                  dataType: Image
                  description: This is an example description
                  evaluationEngine: fae
                  input: 735e766c-25a6-11ec-92f1-0242ac1c0004
                  inputDomain:
                    - '0'
                    - '255'
                  model: 6c294368-25a6-11ec-a08e-0242ac1c0004
                  name: Evaluation Example for an image classifier
                  noise:
                    intensity: '0.0001'
                    mode: BOKEH
                  normalize: true
              TimeSeriesInterpolator:
                value:
                  options:
                    analysisType: float128
                    dataType: TimeSeries
                    description: This is an example description
                    evaluationEngine: fae
                    input: 735e766c-25a6-11ec-92f1-0242ac1c0004
                    inputDomain:
                      - '0'
                      - '255'
                    model: 6c294368-25a6-11ec-a08e-0242ac1c0004
                    name: Evaluation Example for a time-series interpolator
                    noise:
                      intensity: '0.0001'
                      mode: MULTIPLICATIVE
                    normalize: false
      responses:
        '200':
          description: >-
            When creating an evaluation, the backend create a new object and
            return the new evaluation ID along with a confirmation message
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The unique ID associated to this evaluation.
                  evalId:
                    type: string
                    description: The unique ID associated to this evaluation.
              example:
                evalId: 571445e6-a245-11ed-bef3-02420a000089
                message: >-
                  Evaluation succesfully launched, a unique id was automatically
                  assigned to it
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Error during evaluation: 1-bit pixels mode is not supported.'
    get:
      tags:
        - Evaluations
      description: |
        ### Allows the query of all evaluations.

        **Notes:**
          - This request **wont return more than 100 evaluations** at a time. The parameters are meant to be used to iterate with a **pagination system**.
          - A first query will return the **number of matching evaluations** in the `nbResults` field.
          - Use `offset` parameter to **specify the index** of the first evaluation to be returned.
          - The `limit` parameter define the number of evaluations returned **for each query*, it must be in the **interval [1;100]**.
      summary: Get all evaluations
      parameters:
        - in: query
          required: false
          name: filter (not implemented)
          schema:
            type: string
          description: Query syntax to be defined later
        - in: query
          required: false
          name: limit
          schema:
            type: integer
          description: >-
            The number of evaluation to be returned (must be >0 and <= 100,
            default to 100)
        - in: query
          required: false
          name: offset
          schema:
            type: integer
          description: The starting index for selecting the evaluations returned
        - in: query
          required: false
          name: order_by
          schema:
            type: string
          description: >-
            (not implemented, default to `created:desc`, query syntax to be
            defined later)
      responses:
        '200':
          description: All the available evaluations
          content:
            application/json:
              schema:
                type: object
                properties:
                  evaluations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The unique ID associated to this evaluation.
                        name:
                          type: string
                          description: The evaluation's name
                        description:
                          type: string
                          description: The optional evaluation's description
                        inputId:
                          type: string
                          description: >-
                            The id for the input ressource used in this
                            evaluation
                        dataType:
                          type: string
                          description: The type of the input data (Image or TimeSeries)
                        creationDate:
                          type: string
                          description: The evaluation's start date
                        duration:
                          type: string
                          description: The time elapsed to perform the evaluation
                        analysisType:
                          type: string
                          description: >-
                            The analysis type used for this evaluation (float,
                            double or float128)
                        evaluationEngine:
                          type: string
                          description: >-
                            The evaluation engine used for this evaluation
                            (either ad_svm, fae_ts or fae)
                        modelId:
                          type: string
                          description: >-
                            The id for the model ressource used in this
                            evaluation
                        status:
                          enum:
                            - IN_PROGRESS
                            - DONE
                            - FAILED
                          type: string
                          description: 'The evaluation''s status: FAILED, IN_PROGRESS or DONE'
                        inputDomain:
                          type: array
                          items:
                            type: string
                            description: >-
                              (Optional) Given the min/max bound defining the
                              valid domain which must be respected after noise
                              application
                        noise:
                          type: object
                          properties:
                            mode:
                              type: string
                              enum:
                                - NONE
                                - ADDITIVE
                                - MULTIPLICATIVE
                                - BOKEH
                                - GAUSSIAN
                              description: >-
                                (Required) the mode that will be used to create
                                the abstract domain. The mode may induce further
                                parameter requirements. Some parameter are
                                currently hardcoded. If either Bokeh or gaussian
                                is selected, a blur operation is performed on an
                                image which is previously made abstract using
                                the additive noise. Furthermore, some parameters
                                are hardcoded, such as sigma=1.0 and the kernel
                                size = 7x7
                            intensitiy:
                              type: string
                              description: >-
                                Value describing the intensity of the abstract
                                noise applied to the input data
                  nbResults:
                    description: >-
                      The total number of evaluation that can be requested with
                      the current parameters
                    type: integer
              example:
                evaluations:
                  - workspace_path: /Workspace/saimplev2
                    modelId: a8cab14e-e796-11ee-adaa-02420a0000d6
                    inputId: 8c4194f8-e7a4-11ee-b3d4-02420a0000b3
                    status: IN_PROGRESS
                    id: d0afc0d0-f1b6-11ee-8ef9-02420a00002a
                    creationDate: '2024-04-03T14:36:38.258676'
                    evaluationName: sharp_clarke
                    evaluationEngine: fae
                    postProcessing: false
                    name: test (Copy 2)
                    description: ''
                    dataType: TimeSeries
                    inputDomain:
                      - '0'
                      - '255'
                    noise:
                      intensity: '0.00001'
                      mode: ADDITIVE
                    analysisType: float
                    normalize: false
                    startAt: ''
                    outputSelected: ''
                    sanityCheck: ''
                    sanityThreshold: ''
                    force: false
                    endDate: null
                    duration: null
                    inputName: correct.csv
                    modelName: model_cnn_detect_arythm.onnx
                nbResults: 1
        '500':
          description: Internal server error
    delete:
      tags:
        - Evaluations
      summary: Delete all existing evaluations
      description: >
        ### Deletes ALL evaluations in the user workspace

        **Warning:** The evaluations **cannot be restored** after calling this
        route!
      responses:
        '200':
          description: All evaluations were successfully deleted
        '404':
          description: Some or all evaluations couldn't be deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
              example:
                message: Evaluation successfully deleted
        '500':
          description: Internal server error
  /api/v2/evaluations/{evalId}:
    get:
      tags:
        - Evaluations
      summary: Get evaluation details from its ID
      description: |
        ### Returns all available information for an evaluation.
        **Note:** This route has side effects:
          - It will **update the evaluation status** by checking if the evaluation is finished or failed.
          - It is also currently used to **detect the end** of the abstract evaluation:
            - When it's done, it will implicitly **triggers the relevant post-processing**.
            - When all post-processing are done, the **status is updated** accordingly.
      parameters:
        - in: path
          required: true
          name: evalId
          schema:
            type: string
          description: The evaluation's ID
          example: 735e766c-25a6-11ec-92f1-0242ac1c0004
      responses:
        '200':
          description: Details of the specified evaluation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  analysistype:
                    description: >-
                      The analysis type used for this evaluation (float, double
                      or float128)
                    type: string
                  creationdate:
                    description: The evaluation's start date
                    type: string
                  datatype:
                    description: The type of the input data (image or timeseries)
                    type: string
                  description:
                    description: The optional evaluation's description
                    type: string
                  duration:
                    description: The time elapsed to perform the evaluation
                    type: string
                  enddate:
                    description: The evaluation's end date
                    type: string
                  evaluationengine:
                    description: >-
                      The evaluation engine used for this evaluation (either
                      ad_svm, fae_ts or fae)
                    type: string
                  evaluationname:
                    description: >-
                      A user friendly name generated by the backend (the name is
                      not garanted to be unique)
                    type: string
                  id:
                    description: The unique id associated to this evaluation
                    type: string
                  inputdomain:
                    items:
                      description: >-
                        (optional) Given the min/max bound, defining the valid
                        domain which must be respected after noise application
                      type: string
                    type: array
                  inputname:
                    description: The name of the input file
                    type: string
                  inputid:
                    description: The input file ressource used in this evaluation
                    type: string
                  modelid:
                    description: The model used in this evaluation
                    type: string
                  modelname:
                    description: The name for the model file
                    type: string
                  name:
                    description: The evaluation's name (given by the user)
                    type: string
                  noise:
                    properties:
                      intensitiy:
                        description: >-
                          Value describing the intensity of the abstract noise
                          applied to the input data
                        type: string
                      mode:
                        description: >-
                          (required) The mode that will be used to create the
                          abstract domain. This may induce further parameter
                          requirements. Some parameter are currently hardcoded.
                          If bokeh or gaussian is selected, a blur operation is
                          performed on an image which is made abstract using the
                          additive noise. Furthermore, some parameters are
                          hardcoded, such as sigma=1.0 and the kernel size =
                          7x7.
                        enum:
                          - none
                          - additive
                          - multiplicative
                          - bokeh
                          - gaussian
                        type: string
                    type: object
                  normalize:
                    description: Whether the input should be normalized between 0 and 1
                    type: boolean
                  status:
                    description: The evaluation's status (failed, in progress or done)
                    type: string
                  workspace_path:
                    description: The workspace containing this evaluation
                    type: string
              example:
                value:
                  workspace_path: /Workspace/saimplev2
                  modelId: a8cab14e-e796-11ee-adaa-02420a0000d6
                  inputId: 8c4194f8-e7a4-11ee-b3d4-02420a0000b3
                  status: IN_PROGRESS
                  id: d0afc0d0-f1b6-11ee-8ef9-02420a00002a
                  creationDate: '2024-04-03T14:36:38.258676'
                  evaluationName: sharp_clarke
                  postProcessing: false
                  name: test (Copy 2)
                  description: ''
                  dataType: TimeSeries
                  inputDomain:
                    - '0'
                    - '255'
                  noise:
                    intensity: '0.00001'
                    mode: ADDITIVE
                  analysisType: float
                  normalize: false
                  startAt: ''
                  outputSelected: ''
                  sanityCheck: ''
                  sanityThreshold: ''
                  force: false
                  evaluationEngine: fae
                  endDate: null
                  duration: null
                  inputName: correct.csv
                  modelName: model_cnn_detect_arythm.onnx
        '400':
          description: Bad request. The ID must be a string.
        '401':
          description: Unauthorized to retrieve the evaluation.
        '404':
          description: Evaluation with the specified ID was not found.
    delete:
      tags:
        - Evaluations
      summary: Delete an existing evaluation
      description: |
        ### Deletes an existing evaluation by its ID
        **Notes:**
          - This route will remove **all ressources** created during the evaluation and remove the **corresponding reference** for the **model and input** objects.
          - This operation **cannot be undone**.
          - It will **not interrupt** an evaluation and can only be used to remove the artifact and
        free disk space **after the evaluation is finished**.
      parameters:
        - in: path
          required: true
          name: evalId
          schema:
            type: string
          description: The evaluation's ID
          example: hopeful_morse
      responses:
        '200':
          description: Evaluation successfully deleted.
        '400':
          description: Bad request. The id must be a string.
        '404':
          description: Evaluation doesn't exist.
        '500':
          description: Internal server error.
  /api/v2/evaluations/{evalId}/relevance:
    get:
      tags:
        - Relevance
      summary: Get evaluation raw relevance
      description: >
        ### Returns the raw relevance for an evaluation by its ID.

        **Notes:** The **raw relevance** is the relative importance of each
        entry on the final result.


        **Example:** For a **classifier** processing a image in `100 x 100 x 3`
        size and producing **10 classes** score, this route will:
          - return `10 x 100 x 100 x 3` values, which can be projected as **10 relevance image**, one for each class,
          - then project those on the original image to observe the **image feature relative impacts**.
      parameters:
        - in: path
          required: true
          name: evalId
          schema:
            type: string
          description: The evaluation's ID
        - in: query
          required: false
          name: svm_mode
          schema:
            type: string
            enum:
              - hog
              - square
          description: >-
            Selection of the projection method of the relevance, either from an
            interpretation of the relevance computed from the hog edges or from
            the hog grid cell
      responses:
        '200':
          description: Get relevance result for a specific evaluation by its ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: array
                      items:
                        type: number
                    example:
                      value:
                        - - - 0.21324
                            - ...
                            - -0.4231
                          - - ...
                          - - 0.90414
                            - ...
                            - -0.5851
                  shape:
                    type: string
                    example: (20, 30, 30)
        '400':
          description: Bad request. Evaluation ID must be a string.
        '401':
          description: Unauthorized to get the relevance.
        '404':
          description: Relevance result with the specified ID was not found.
        '500':
          description: Internal server error.
  /api/v2/evaluations/{evalId}/dominance:
    get:
      tags:
        - Dominance
      summary: Get evaluation dominance
      description: |
        ### Gets dominance for a given evaluation byt its ID
        **Notes:**
          - The dominance is mostly used with **classifier models**.
          - This route returns the **range of possible values for each predictions**.
          - It also gives the **dominant class**, if one of them was **predicted** with a **class score always greater** than all the others.
          - The **dominance computation** is applied directly on the **abstract domain** and **not** on the **returned interval**.
          - It's possible to have **overlapping interval** and to still obtain the **dominance** property.
      parameters:
        - in: path
          required: true
          name: evalId
          schema:
            type: string
          description: The evaluation's ID
      responses:
        '200':
          description: Get dominance result for a specific evaluation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  classes:
                    type: object
                    properties:
                      classes:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: The identifier of the output class
                            example: 0
                          min:
                            type: number
                            description: >-
                              The lower bound of the output interval for this
                              class
                            example: 0.15124
                          max:
                            type: number
                            description: >-
                              The upper bound of the output interval for this
                              class
                            example: 0.9995
                          status:
                            type: string
                            description: >-
                              Indicates the dominance status, i.e whether this
                              class is 'Dominant', 'Dominated' or in 'Conflict'
                            example: Dominant
                    example:
                      - id: 0
                        min: 0.4087343215942383
                        max: 0.41489797830581665
                        status: Dominated
                      - id: 1
                        min: 0.0000052851514737994876
                        max: 0.000005388831596064847
                        status: Dominated
                      - id: 2
                        min: 0.5850964188575745
                        max: 0.5912600159645081
                        status: Dominant
                      - id: 3
                        min: 3.340790328820731e-7
                        max: 3.409666931020183e-7
                        status: Dominated
                      - id: 4
                        min: 2.515270436376227e-9
                        max: 2.5899780098370684e-9
                        status: Dominated
        '400':
          description: Bad request. Evaluation id must be a string.
        '401':
          description: Unauthorized to get the dominance.
        '404':
          description: Dominance result with the specified ID was not found.
  /api/v2/evaluations/{evalId}/trace:
    get:
      summary: Get evaluation raw relevance
      tags:
        - Evaluations
      description: >
        ### Returns the execution trace for the given evaluation.

        **Notes:** The **trace** can be requested while the evaluation is still
        running, it can be used to monitor its progression.

        The "out" and "err" parameters are captured from the evaluation engine
        stdout and stderr stream. The layers informations is formated by the
        engine.

        The parsedStandardError is a formatted version of the 'err' field and
        might not contains all informations
      parameters:
        - in: path
          required: true
          name: evalId
          schema:
            type: string
          description: The evaluation's ID
      responses:
        '200':
          description: the
          content:
            application/json:
              schema:
                type: object
                properties:
                  out:
                    type: string
                    description: The raw stdout string from the evaluation engine.
                  err:
                    type: string
                    description: The raw stderr string from the evaluation engine.
                  parsedStandardError:
                    type: object
                    description: >-
                      A json document containing what informations could be
                      parsed from the raw stderr.
                    properties:
                      timeVInfo:
                        type: object
                        description: >-
                          The fields parsed from the '/usr/bin/time -v
                          executable used to wrap up the evaluation execution
                      errorLines:
                        type: array
                        description: A list of lines which contain an error like pattern.
                        items:
                          type: string
                      stacktraces:
                        type: array
                        description: >-
                          A list of lines which contain a python Stacktrace like
                          pattern.
                        items:
                          type: string
                  layersTrace:
                    type: object
                    description: >-
                      A json document containing the informations for each
                      layers processed by the engine
  /api/v2/inputs:
    get:
      summary: Get the list of all inputs
      description: |
        ### Returns a list of all inputs
        **Notes:** The pagination mechanism is not yet implemented.
      tags:
        - Inputs
      responses:
        '200':
          description: All available inputs
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    items:
                      properties:
                        creationDate:
                          example: 26/05/2021-11:15:19
                          type: string
                          description: That creation date of the input
                        evaluations:
                          example: []
                          items:
                            type: string
                          type: array
                          description: >-
                            The list of evaluations that contain a reference to
                            this input
                        fileName:
                          example: e4174818-be02-11eb-965e-65d067e2ea43.jpg
                          type: string
                          description: The generated file name of the input
                        format:
                          example: Image
                          type: string
                          description: The input's format
                        id:
                          example: e4174818-be02-11eb-965e-65d067e2ea43
                          type: string
                          description: The input's identifier
                        originalFileName:
                          example: example_5.JPG
                          type: string
                          description: The original name of the uploaded input
                      type: object
                    type: array
                example:
                  inputs:
                    - id: b7a9c77e-c39d-11eb-a489-57b77f61e701
                      creationDate: 26/05/2021-11:15:19
                      originalFileName: example_3.JPG
                      fileName: b7a9c77e-c39d-11eb-a489-57b77f61e701.jpg
                      format: Image
                      evaluations: []
                    - id: e4174818-be02-11eb-965e-65d067e2ea43
                      creationDate: 26/05/2021-11:15:19
                      originalFileName: example_5.JPG
                      fileName: e4174818-be02-11eb-965e-65d067e2ea43.jpg
                      format: Image
                      evaluations:
                        - some_evalution_id
        '500':
          description: Internal server error.
    post:
      tags:
        - Inputs
      summary: Upload a new input data file
      description: |
        ### Allows upload of a new input
        **Notes:**
          - Input **must have an extension** in the following list:
            - .jpg / .jpeg
            - .png
            - .tif / .tiff
            - .raw
            - .csv
            - .npy
          - On **success**, the route **returns the ID associated** with the uploaded input
      requestBody:
        description: >-
          An Image (.jpg, .jpeg, .png, .tif, .tiff .raw)  or a TimeSeries (.csv,
          .npy) file to upload
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filedata:
                  type: object
                  format: binary
                  description: The binary file of the input data
            examples:
              Image Data:
                value:
                  multipart/form-data:
                    files:
                      filedata: <example_image.jpg>
                    reference: 5
              TimeSeries Data:
                value:
                  multipart/form-data:
                    files:
                      filedata: <timeseries.csv>
                    reference: 5
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  fileId:
                    type: string
                    example: 111-222-333
                    description: The generated input's identifier
                  fileName:
                    type: string
                    example: mnist_0.jpg
                    description: The uploaded input's name
        '500':
          description: Internal server error
    delete:
      tags:
        - Inputs
      summary: Delete all existing inputs
      description: |
        ### Deletes all existing inputs data files for the current workspace
        **Notes:** This operation **cannot be reverted**.
      responses:
        '200':
          description: All the inputs data files were successfully deleted.
        '400':
          description: Deletion failed.
        '500':
          description: Internal server error.
  /api/v2/inputs/{fileId}/file:
    get:
      tags:
        - Inputs
      summary: Get an input data file
      description: |
        ### Returns the specified input data file
      parameters:
        - in: path
          required: true
          name: fileId
          schema:
            type: string
          description: The file identifier of the specified input
      responses:
        '200':
          description: The specified input data file
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
              example: filedata
        '300':
          description: >-
            When given a name matching more than one input, returns the list of
            possible choices
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Error, too many files found with name : mnist_input.png'
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/inputs/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/inputs/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '400':
          description: Invalid request, fileName / fileId must be a string.
        '404':
          description: The file was not found.
        '500':
          description: Internal server error.
  /api/v2/inputs/{fileId}/meta:
    get:
      tags:
        - Inputs
      summary: Get an input metadata
      description: |
        ### Returns the specified input metadata
      parameters:
        - in: path
          required: true
          name: fileId
          schema:
            type: string
          description: The file name or identifier of the specified input
      responses:
        '200':
          description: The specified input metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  creationDate:
                    example: '2021-10-06T11:34:22.103850'
                    type: string
                    description: The input's creation date
                  evaluations:
                    items:
                      example: []
                      type: string
                    type: array
                    description: >-
                      The evaluations list which contain a reference to this
                      input
                  fileName:
                    example: e4174818-be02-11eb-965e-65d067e2ea43.jpg
                    type: string
                    description: The generated file name of the input
                  format:
                    example: Image
                    type: string
                    description: The input's format
                  id:
                    example: e4174818-be02-11eb-965e-65d067e2ea43
                    type: string
                    description: The input's identifier
                  originalFileName:
                    example: example_5.JPG
                    type: string
                    description: The original name of the uploaded input
              example:
                id: e4174818-be02-11eb-965e-65d067e2ea43
                creationDate: 26/05/2021-11:15:19
                originalFileName: example_5.JPG
                fileName: e4174818-be02-11eb-965e-65d067e2ea43.jpg
                format: Image
                evaluations: []
        '300':
          description: >-
            When given a name matching more than one input, returns the list of
            possible choices
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Error, too many files found with name : mnist_input.png'
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/inputs/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/inputs/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '400':
          description: Invalid request, fileName / fileId must be a string.
        '404':
          description: The file was not found.
        '500':
          description: Internal server error.
  /api/v2/inputs/{fileId}:
    delete:
      tags:
        - Inputs
      summary: Delete an existing input
      description: >
        ### Deletes the specified input and its data files

        **Note:** The route itself **allows the suppression** of inputs that are
        **being used by evaluations**. This may render

        them **inexploitable**. The **frontend application** emits an alert and
        offers to delete the associated evaluations but **not the API**.
      parameters:
        - in: path
          required: true
          name: fileId
          schema:
            type: string
          description: The file name or identifier of the specified input
      responses:
        '200':
          description: Input data file successfully deleted.
        '300':
          description: >-
            When given a name matching more than one input, return the list of
            possible choices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: 'Error, too many files found with name : mnist_input.png'
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/inputs/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/inputs/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '404':
          description: Input data file not found.
        '500':
          description: Internal server error.
  /api/v2/models:
    post:
      tags:
        - Models
      summary: Upload a new model file
      description: >
        ### Allows the upload of a compatible neural network model (*.h5,
        *.onnx) or svm (.npy)

        **Notes:** On reception of the model, the backend will try to **parse**
        it to extract the model **expected input shape**.

        On reception, the model the backend will check is the same file already
        existe in the user workspace to avoid duplication.

        If the model already exist, the api return a http 200 response with the
        existing file id
      requestBody:
        description: The model file to upload
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                model:
                  type: object
                  format: binary
            example:
              multipart/form-data:
                files:
                  model: <test.h5>
      responses:
        '200':
          description: Model already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  modelId:
                    type: string
                    example: 222-333-444
                    description: The duplicate file identifier
                  modelName:
                    type: string
                    example: mnist.h5
                    description: The uploaded model's file name
        '201':
          description: Model resource created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  modelId:
                    type: string
                    example: 222-333-444
                    description: The generated model's identifier
                  modelName:
                    type: string
                    example: mnist.h5
                    description: The uploaded model's file name
        '400':
          description: Invalid request content.
        '500':
          description: Internal server error.
    get:
      tags:
        - Models
      summary: Get all existing models
      description: |
        ### Returns all previously uploaded models.
      responses:
        '201':
          description: The list of already uploaded models
          content:
            application/json:
              schema:
                type: object
                properties:
                  models:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: e091d492-be02-11eb-965e-65d067e2ea43
                          description: The model's identifier
                        creationDate:
                          type: string
                          example: 26/05/2021-11:15:13
                          description: The model's creation date
                        originalFileName:
                          type: string
                          example: Sign_language_Digits.h5
                          description: The model's original file name
                        fileName:
                          type: string
                          example: e091d492-be02-11eb-965e-65d067e2ea43.h5
                          description: The model's generated file name
                        format:
                          type: string
                          example: format
                          description: The model's format
                        source:
                          type: string
                          example: null
                          description: The model's source
                        modelFingerprint:
                          type: string
                          example: a709666cd8efe575967d6fdf18b18e22
                          description: the model file hash key
                        modelSize:
                          type: integer
                          example: 4577456
                          description: the model file size in byte
                        labels:
                          type: string
                          example: null
                          description: The model's labels
                        inputShape:
                          type: array
                          items:
                            type: number
                            example:
                              - 100
                              - 100
                              - 3
                            description: The model's input shape
                        evaluations:
                          type: array
                          items:
                            type: string
                            example:
                              - some_eval_id
                            description: >-
                              The list of evaluations that contain a reference
                              to the model
                    example:
                      models:
                        - id: e091d492-be02-11eb-965e-65d067e2ea43
                          creationDate: 26/05/2021-11:15:13
                          originalFileName: Sign_language_Digits.h5
                          fileName: e091d492-be02-11eb-965e-65d067e2ea43.h5
                          format: keras
                          source: null
                          labels: null
                          modelFingerprint: a709666cd8efe575967d6fdf18b18e22
                          modelSize": 4577456
                          evaluations: []
                          inputShape:
                            - 100
                            - 100
                            - 3
                        - id: 65d067e2-be02-11eb-965e-ea43e091d492
                          creationDate: 22/03/2021-15:11:31
                          originalFileName: mnist.h5
                          fileName: 65d067e2-be02-11eb-965e-ea43e091d492.h5
                          format: keras
                          modelFingerprint: a709666cd8efe575967d6fdf18b18e22
                          modelSize": 4577456
                          source: null
                          labels: null
                          evaluations:
                            - some_eval_id
                          inputShape:
                            - 28
                            - 28
                            - 1
        '500':
          description: Internal server error
    delete:
      tags:
        - Models
      summary: Delete all existing models
      description: |
        ### Deletes all existing models for the current user
        **Notes:** This operation **cannot be reverted**.
      responses:
        '200':
          description: All models files were successfully deleted
        '400':
          description: Deletion failed
        '500':
          description: Internal server error
  /api/v2/models/{modelId}/file:
    get:
      tags:
        - Models
      summary: Get a model's files
      description: |
        ### Returns the specified model's files
      parameters:
        - in: path
          required: true
          name: modelId
          schema:
            type: string
          description: The model's identifier
      responses:
        '201':
          description: The specified model file
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
              example: filedata
        '300':
          description: >-
            When given a name matching more than one model, returns the list of
            possible choices
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Error: too many files found with name :
                      fashion_mnist_duplicate.h5
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/models/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/models/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '400':
          description: Bad request. The model name / id must be a string.
        '404':
          description: The model couldn't be found
        '500':
          description: Internal server error
  /api/v2/models/{modelId}/validate:
    patch:
      tags:
        - Models
      summary: Check that the given model is valid for the evaluation engine
      description: >
        ### Returns a json with an "ok" or "ko" value, indicating wether the
        model is supported or not by the evaluation engine.

        If the status is "ko", a list of error is provided.
      parameters:
        - in: path
          required: true
          name: modelId
          schema:
            type: string
          description: The model's identifier
      responses:
        '200':
          description: The specified model file metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_version:
                    type: string
                    example: '0.1'
                    description: the version for the json document
                  status:
                    type: string
                    example: ok
                    enum:
                      - ok
                      - ko
                    description: Wether the model pass the validation or not
                  errors:
                    type: array
                    items:
                      type: string
                    description: The list or error encountered while validating the model
                    example: []
        '400':
          description: Bad request. The model id must be a valid UUIDv1.
        '404':
          description: The model couldn't be found
        '500':
          description: Internal server error
  /api/v2/models/{modelId}/meta:
    get:
      tags:
        - Models
      summary: Get a model's metadata
      description: |
        ### Returns the specified model's metadata
      parameters:
        - in: path
          required: true
          name: modelId
          schema:
            type: string
          description: The model's identifier
      responses:
        '201':
          description: The specified model file metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: e091d492-be02-11eb-965e-65d067e2ea43
                    description: The model's identifier
                  creationDate:
                    type: string
                    example: 26/05/2021-11:15:13
                    description: The model's creation date
                  originalFileName:
                    type: string
                    example: Sign_language_Digits.h5
                    description: The model's original file name
                  fileName:
                    type: string
                    example: e091d492-be02-11eb-965e-65d067e2ea43.h5
                    description: The model's generated file name
                  format:
                    type: string
                    example: format
                    description: The model's format
                  source:
                    type: string
                    example: null
                    description: The model's source
                  modelFingerprint:
                    type: string
                    example: a709666cd8efe575967d6fdf18b18e22
                    description: the model file hash key
                  modelSize:
                    type: integer
                    example: 4577456
                    description: the model file size in byte
                  labels:
                    type: string
                    example: null
                    description: The model's labels
                  inputShape:
                    type: array
                    items:
                      type: number
                      example:
                        - 100
                        - 100
                        - 3
                      description: The model's input shape
                  oriShape:
                    type: array
                    items:
                      type: number
                      example:
                        - 96
                        - 96
                      description: On svm model only
                  hogShape:
                    type: array
                    items:
                      type: number
                      example:
                        - 12
                        - 12
                        - 9
                      description: On svm model only
                  evaluations:
                    type: array
                    items:
                      type: string
                      example:
                        - some_eval_id
                      description: >-
                        The list of evaluations that contain a reference to the
                        model
              example:
                id: e091d492-be02-11eb-965e-65d067e2ea43
                creationDate: 26/05/2021-11:15:13
                originalFileName: Sign_language_Digits.h5
                fileName: e091d492-be02-11eb-965e-65d067e2ea43.h5
                format: keras
                modelFingerprint: a709666cd8efe575967d6fdf18b18e22
                modelSize: 4577456
                source: null
                labels: null
                inputShape:
                  - 100
                  - 100
                  - 3
                evaluations: []
        '300':
          description: >-
            When given a name matching more than one model, returns the list of
            possible choices
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Error, too many files found with name :
                      fashion_mnist_duplicate.h5
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/models/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/models/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '400':
          description: Bad request. The model id must be a valid UUIDv1.
        '404':
          description: The model couldn't be found
        '500':
          description: Internal server error
  /api/v2/models/{modelId}:
    delete:
      tags:
        - Models
      summary: Delete an existing model
      description: >
        ### Deletes the specified model and its data files

        **Note:** The route itself **allows the suppression** of models that are
        **being used by evaluations**. This may render

        them **inexploitable**. The **frontend application** emits an alert and
        offers to delete the associated evaluations but **not the API**.
      parameters:
        - in: path
          required: true
          name: modelId
          schema:
            type: string
          description: The model's identifier
      responses:
        '201':
          description: Specified model successfully deleted
        '300':
          description: >-
            When given a name matching more than one model, returns the list of
            possible choices
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Error: too many files found with name :
                      fashion_mnist_duplicate.h5
                  locations:
                    type: array
                    items:
                      type: string
                    example:
                      - /api/v2/models/8cf960dc-d263-11eb-88d4-989096a74a30/meta
                      - /api/v2/models/8cff5424-d263-11eb-88d4-989096a74a30/meta
                  matching_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - 8cf960dc-d263-11eb-88d4-989096a74a30
                      - 8cff5424-d263-11eb-88d4-989096a74a30
        '400':
          description: Bad request. The model name / ID must be a string.
        '404':
          description: The model couldn't be found
        '500':
          description: Internal server error
  /api/v2/authentification:
    post:
      tags:
        - Utils
      summary: User authentication
      description: |
        ### Allows user authentication with login and password.
        **Notes:**
          - This route **should be the first** one called when **starting a user session**.
          - Takes **login/password as parameters**.
          - Returns a **token** used to check the user credentials, allowing them to **access its workspace ressources** (input, model, evaluations)...
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - login
                - password
              properties:
                login:
                  type: string
                  description: The login used for authentication
                password:
                  type: string
                  description: The password used for authentication
            examples:
              frontend:
                summary: When the license check is disabled
                value:
                  login: saimplev2
                  password: saimplev2
      responses:
        '200':
          description: API is reachable
          content:
            application/json:
              schema:
                type: object
              examples:
                token_ok:
                  value:
                    access_token: XXX
                    expires_in: 36000
                    not-before-policy: 1635352754
                    refresh_expires_in: 1800
                    refresh_token: YYY
                    scope: email profile
                    session_state: 064a6909-7d25-4cdd-bb8e-1cb027ca4e42
                    token_type: Bearer
  /api/v2/status:
    get:
      tags:
        - Utils
      summary: Get API Status
      description: >
        ### Gets API Status

        **Notes:** This route is mostly used by application to **ensure the
        availability of the backend**.
      responses:
        '200':
          description: API is reachable
  /api/v2/supported-layers:
    get:
      tags:
        - Utils
      summary: Get supported layers
      description: >
        ### Gets the list of supported layers in the evaluation engine and their
        supported onnx versions.
      responses:
        '200':
          description: The "list of supported layers"
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_version:
                    type: string
                    example: '0.2'
                    description: The version of the file
                  Description:
                    type: string
                    example: '0.2'
                    description: The description of the file
                  Activation_functions:
                    type: array
                    items:
                      type: object
                      description: The activation functions
                      properties:
                        act_fun_name:
                          type: object
                          properties:
                            onnx_op_version:
                              type: array
                              items:
                                type: integer
                  binary_operators:
                    type: array
                    description: The binary operators
                    items:
                      type: object
                      properties:
                        binop_name:
                          type: object
                          properties:
                            onnx_op_version:
                              type: array
                              items:
                                type: integer
                  form_operators:
                    type: array
                    description: The form operators
                    items:
                      type: object
                      properties:
                        form_op_name:
                          type: object
                          properties:
                            onnx_op_version:
                              type: array
                              items:
                                type: integer
                  layers:
                    type: array
                    description: Layers
                    items:
                      type: object
                      properties:
                        layer_name:
                          type: object
                          properties:
                            onnx_op_version:
                              type: array
                              items:
                                type: integer
        '500':
          description: Internal server error
  /api/v2/versions:
    get:
      tags:
        - Utils
      summary: Get versions of the different Saimple entities
      description: |
        ### Gets the versions of the different Saimple entities.
      responses:
        '200':
          description: API is reachable
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      version:
                        type: string
                        example: 4.0.0
                        description: The entity's version name
                  fae:
                    type: object
                    properties:
                      build:
                        type: string
                        example: 2021-09-30 - 16:59
                        description: The creation date of the build
                      commit:
                        type: string
                        example: 6f74047d490e71f61b8544a9015f933a1e77e608
                        description: The commit's hash
                      tags:
                        type: array
                        items:
                          type: string
                        example:
                          - tag1
                          - tag2
                        description: The entity's tags
                      version:
                        type: string
                        example: 0.91.1-21W36
                        description: The entity's version name
                  fae-libAD:
                    type: object
                    properties:
                      build:
                        type: string
                        example: 2021-09-30 - 16:58
                        description: The creation date of the build
                      commit:
                        type: string
                        example: 8bae5ffdc0340a775f6a0bae8c50724935f9c940
                        description: The commit's hash
                      tags:
                        type: array
                        items:
                          type: string
                        example:
                          - tag1
                          - tag2
                        description: The entity's tags
                      version:
                        type: string
                        example: v0.91.1 - 21W36
                        description: The entity's version name
                  abstari:
                    type: object
                    properties:
                      version:
                        type: string
                        example: v0.91.1 - 21W36
                        description: The entity's version name
                      additional_info:
                        type: array
                        items:
                          type: string
                        example:
                          - ''
                        description: Additional information about the entity
        '500':
          description: Internal server error
  /api/v2/license:
    get:
      tags:
        - Utils
      summary: Get license informations of the different Saimple entities
      description: |
        ### Gets the license informations of the different Saimple entities.
      responses:
        '200':
          description: API is reachable
          content:
            application/json:
              schema:
                type: object
              examples:
                disabled:
                  summary: When the license check is disabled
                  value:
                    check_msg: ''
                    expiration_date: ''
                    hostid: ''
                    license_path: ''
                    license_check: DISABLED
                    product: ''
                    product_version: ''
                    start: ''
                    client: ''
                    is_valid: true
                enabled:
                  summary: When the license is checked
                  value:
                    license check: ENABLED
                    hostid: 989096a74a30
                    product: fae
                    product_version: '1.0'
                    start: ''
                    expiration_date: 01-dec-2021
                    'license_path: /home/quentin': null
                    'license_file: /home/quentin/Caffeine_license.lic': null
                    check_msg: No error
                    client: ''
                    is_valid: true
        '500':
          description: Server couldn't be reached
