swagger: '2.0'
info:
  title: KubeEdge Model and Dataset Management API
  version: '0.1.0'
  x-visibility: external
  contact:
    email: "xxx@xxx.com"
  license:
    name: "Apache 2.0"
  description: >-
    KubeEdge Machine Learning management API
schemes:
  - https
  - http
basePath: /KubeEdgeAPI/ML_management/v1
paths:
  '/models':
    post:
      tags:
        - models
      summary: deploy a model to Edge Cloud.
      description: deploy a model and register it to edge cloud
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          type: file
          required: true
          description: The model file
        - name: modelInfo
          in: formData
          required: true
          type: string
          description: model information
      responses:
        '201':
          description: >-
            The model and metadata were uploaded successfully. Returns the details regarding the newly created model
          schema:
            $ref: '#/definitions/Model'
        '400':
          $ref: '#/responses/400-wrong-param'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
  '/models/{modelId}':
    get:
      tags:
        - models
      summary: Return model details.
      description: model's metadata (name, description, owner, date etc.).
      consumes:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Model ID
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Model'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    patch:
      tags:
        - models
      summary: Updates the model's info.
      description: update model's metadata (name, description, owner, date etc.).
      consumes:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: model ID
          required: true
          type: string
        - in: body
          name: model
          required: true
          schema:
            $ref: '#/definitions/ModelDefinition'
      responses:
        '200':
          description: The model info is updated
          schema:
            $ref: '#/definitions/Model'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    delete:
      tags:
        - models
      summary: remove a model from edge cloud
      description: remove a model version or all versions
      consumes:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: model ID to be removed 
          required: true
          type: string
      responses:
        '204':
          description: This model is removed from Edge Cloud
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
  '/datasets':
    post:
      tags:
        - datasets
      summary: deploy a dataset to Edge Cloud.
      description: deploy a dataset and register it to edge cloud
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          type: file
          required: true
          description: The dataset file
        - name: datasetInfo
          in: formData
          required: true
          type: string
          description: dataset information
      responses:
        '201':
          description: The dataset and metadata were uploaded successfully.
          schema:
            $ref: '#/definitions/Dataset'
        '400':
          $ref: '#/responses/400-wrong-param'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
  '/datasets/{datasetId}':
    get:
      tags:
        - datasets
      summary: Return a dataset details.
      description: dataset's metadata (name, description, owner, date etc.).
      consumes:
        - application/json
      parameters:
        - name: datasetId
          in: path
          description: dataset ID
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Dataset'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    patch:
      tags:
        - datasets
      summary: Updates the dataset's info.
      description: update dataset's metadata (name, description, owner, date etc.).
      consumes:
        - application/json
      parameters:
        - name: datasetId
          in: path
          description: dataset ID
          required: true
          type: string
        - in: body
          name: dataset
          required: true
          schema:
            $ref: '#/definitions/DatasetDefinition'
      responses:
        '200':
          description: The dataset info is updated
          schema:
            $ref: '#/definitions/Dataset'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    delete:
      tags:
        - datasets
      summary: remove a dataset from edge cloud
      description: remove a dataset version or all versions
      consumes:
        - application/json
      parameters:
        - name: datasetId
          in: path
          description: dataset ID to be removed 
          required: true
          type: string
      responses:
        '204':
          description: This dataset is removed from Edge Cloud
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
responses:
  500-internal:
    description: Error during execution
    schema:
      $ref: '#/definitions/Errors'
  400-wrong-param:
    description: parameters are missing or wrong format
    schema:
      $ref: '#/definitions/Errors'
  404-not-found:
    description: API not found
    schema:
      $ref: '#/definitions/Errors'
  403-unauth:
    description: The user does not have permission for this endpoint
    schema:
      $ref: '#/definitions/Errors'
definitions:
  Model:
    type: object
    properties:
      id:
        type: string
        format: uuid
      name:
        type: string
        example: emotion_rec
      description:
        type: string
        example: emotion_recognition
      type:
        type: string
        example: CNN
      owner:
        type: string
        example: XXX
      Version:
        $ref: '#/definitions/Version'
  ModelArray:
    type: object
    properties:
      models:
        type: array
        items:
          $ref: '#/definitions/Model'
  Version:
    type: object
    description: >-
      Returned version, owner and  date.
    properties:
      id:
        type: string
        format: uuid
      versionNumber:
        type: number
        example: 0.1
      Date:
        type: string
        format: date
      owner:
        type: string
        example: XXX
  ModelDefinition:
    type: object
    properties:
      name:
        type: string
        example: emotion recognition
      description:
        type: string
        example: emotion recognition
      type:
        type: string
  Dataset:
    type: object
    properties:
      id:
        type: string
        format: uuid
      name:
        type: string
      description:
        type: string
        example: Facial dataset
      owner:
        type: string
        example: XXX
      Version:
        $ref: '#/definitions/Version'
  DatasetArray:
    type: object
    properties:
      models:
        type: array
        items:
          $ref: '#/definitions/Dataset'
  DatasetDefinition:
    type: object
    properties:
      name:
        type: string
        example: facial
      description:
        type: string
        example: facial
      type:
        type: string        
  ErrorMessage:
    type: object
    properties:
      code:
        type: string
        example: kubeedge.mlmanagement.error 
        readOnly: true
      message:
        type: string
        example: Error message
        readOnly: true
  Errors:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorMessage'
