mistk-transform-api.yaml

---
swagger: "2.0"
info:
  version: "1.0.0"
  title: "Model Integration Software ToolKit - Data Transformation"
basePath: "/v1/mistk/transform"
schemes:
- "http"
consumes:
- "application/json"
produces:
- "application/json"
paths:
  /transform:
    post:
      tags:
      - "Transform Plugin Endpoint"
      summary: "Performs the transforms defined for this plugin"
      operationId: "transform"
      parameters:
      - in: "body"
        name: "initParams"
        description: "A list of directory paths where input files can be found."
        required: true
        schema:
          $ref: "#/definitions/TransformSpecificationInitParams"
      responses:
        200:
          description: "Executing transforms"
        405:
          description: "Invalid input"
          schema:
            $ref: "#/definitions/ServiceError"
        500:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/ServiceError"
      x-swagger-router-controller: "mistk.transform.service"
  /status:
    get:
      tags:
      - "Transform Plugin Endpoint"
      summary: "Retrieves the status of the transform plugin"
      operationId: "get_status"
      parameters:
      - name: "watch"
        in: "query"
        description: "Watch for changes to the described resources and return them\
          \ as a stream of add, update, and remove notifications. Specify resourceVersion.\n"
        required: false
        type: "boolean"
      - name: "resourceVersion"
        in: "query"
        description: "When specified with a watch call, shows changes that occur after\
          \ that particular version of a resource. Defaults to changes from the beginning\
          \ of history.\n"
        required: false
        type: "number"
      responses:
        200:
          description: "The status of the Transform Plugin"
          schema:
            $ref: "#/definitions/TransformInstanceStatus"
        500:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/ServiceError"
      x-swagger-router-controller: "mistk.transform.service"
  /shutdown:
    post:
      tags:
      - "Transform Plugin Endpoint"
      summary: "Shutdowns the transform plugin and cleans up any resources."
      operationId: "terminate"
      parameters: []
      responses:
        200:
          description: "Transform Plugin successfully shutdown"
        500:
          description: "Unexpected error"
          schema:
            $ref: "#/definitions/ServiceError"
      x-swagger-router-controller: "mistk.transform.service"
  /apiVersion:
    get:
      tags:
      - "Transform Plugin Endpoint"
      summary: "Returns the version of the MISTK API"
      description: "Returns the version of the MISTK API"
      operationId: "get_api_version"
      parameters: []
      responses:
        200:
          description: "The MISTK API Version\n"
          schema:
            type: "string"
        500:
          description: "General server runtime exception"
      x-swagger-router-controller: "mistk.transform.service"
definitions:
  TransformSpecificationInitParams:
    type: "object"
    required:
    - "inputDatasets"
    properties:
      inputDatasets:
        type: "array"
        description: "A list of directory paths where input files can be found."
        items:
          $ref: "#/definitions/MistkDataset"
      outputDataset:
        description: "A list of directory paths where output files will be saved"
        $ref: "#/definitions/MistkDataset"
      properties:
        type: "object"
        description: "A dictionary of key value pairs for transform plugin arguments."
        properties: {}
    description: "The intialization parameters used by the Transform Specification\
      \ when calling its initialize fuction\n"
    example:
      outputDataset: ""
      inputDatasets:
      - ""
      - ""
      properties: "{}"
  ServiceError:
    type: "object"
    required:
    - "message"
    properties:
      code:
        type: "integer"
        format: "int32"
      message:
        type: "string"
    description: "An custom error class used by component services"
  TransformInstanceStatus:
    type: "object"
    required:
    - "objectInfo"
    properties:
      objectInfo:
        $ref: "#/definitions/ObjectInfo"
      state:
        type: "string"
        description: "The current state of the transform instance"
        enum:
        - "started"
        - "initializing"
        - "initialized"
        - "failed"
        - "ready"
        - "transforming"
        - "completed"
      payload:
        type: "object"
        description: "Additional arbitrary information relevant to the current state.\
          \        \n"
        properties: {}
    description: "A transform instance status object represents the state of a running\
      \ transform instance. \n"
    example:
      payload: "{}"
      state: "started"
      objectInfo:
        summary: "summary"
        owner: "owner"
        creationTime: "2000-01-23T04:56:07.000+00:00"
        kind: "kind"
        displayName: "displayName"
        resourceVersion: 0
        description: "description"
        project: "project"
        resources:
        - "resources"
        - "resources"
        labels: "{}"
        public: true
        modificationTime: "2000-01-23T04:56:07.000+00:00"
        name: "name"
        id: "046b6c7f-0b8a-43b9-b35d-6489e6daee91"
  ObjectInfo:
    type: "object"
    properties:
      kind:
        type: "string"
        description: "This is the type of the resource (e.g., Model, Dataset). The\
          \ field is primarily used when returning watch events, where the type of\
          \ the field will be unknown.  When submitting resources, this field will\
          \ often simply be inferred from the context of the submission.\n"
      id:
        type: "string"
        format: "uuid"
        description: "The unique identifier of the object.  This will be generated\
          \ automatically.\n"
      name:
        type: "string"
        description: "The unique name of the object. Names of SML resources should\
          \ be up to maximum length of 253 characters and consist of lower case alphanumeric\
          \ characters, -, and .\n"
      displayName:
        type: "string"
        description: "The name of this resoure, as presented via this UI.  This field\
          \ can have spaces and upper and lower case alphanumeric  characters as well\
          \ as spaces.\n"
      description:
        type: "string"
        description: "A documentation description of the resource.  This string can\
          \ be in Markdown form.\n"
      summary:
        type: "string"
        description: "A short description of this object\n"
      owner:
        type: "string"
        description: "The owner/creator of this object.\n"
      project:
        type: "string"
        description: "The project for this object (assuming the resource is project-scoped)\n"
      public:
        type: "boolean"
        description: "Boolean flag indicating whether this resource will be  accessible\
          \ to members outside of the project\n"
      labels:
        type: "object"
        description: "Key-value pairs of annotations associate with the object.\n"
        properties: {}
      resources:
        type: "array"
        description: "An array of resources/reference URIs\n"
        items:
          type: "string"
      resourceVersion:
        type: "integer"
        description: "This is the server-managed version for the object.  It is used\
          \  to support monitoring of resources.  This should not be set by the client\
          \ (and will likely be ignored if it is)\n"
      creationTime:
        type: "string"
        format: "date-time"
        description: "The date time at which this object was initially created. This\
          \ will be auto generated by the underlying database. Any user input for\
          \ this field will be ignored. This will be in the isoformat of 'YYYY-MM-DDTHH:MM:SS.ffffff'\n"
      modificationTime:
        type: "string"
        format: "date-time"
        description: "The date time at which this object was last modified. This will\
          \ be auto generated by the underlying database. Any user input for this\
          \ field will be ignored. This will be in the isoformat of 'YYYY-MM-DDTHH:MM:SS.ffffff'\n"
    description: "This is the set of fields common to all objects."
    example:
      summary: "summary"
      owner: "owner"
      creationTime: "2000-01-23T04:56:07.000+00:00"
      kind: "kind"
      displayName: "displayName"
      resourceVersion: 0
      description: "description"
      project: "project"
      resources:
      - "resources"
      - "resources"
      labels: "{}"
      public: true
      modificationTime: "2000-01-23T04:56:07.000+00:00"
      name: "name"
      id: "046b6c7f-0b8a-43b9-b35d-6489e6daee91"
  MistkDataset:
    allOf:
    - $ref: "#/definitions/Dataset"
    - type: "object"
      properties:
        dataPath:
          type: "string"
  Dataset:
    type: "object"
    required:
    - "objectInfo"
    properties:
      objectInfo:
        $ref: "#/definitions/ObjectInfo"
      datastashId:
        type: "string"
        description: "The id of the datastash associated with this dataset where all\
          \ of its files will be stored.\n"
      datastashSubDir:
        type: "string"
        description: "This field denotes the sub path within the datastash where this\
          \ dataset's data resides.\n"
      modality:
        type: "string"
        description: "The type of the data, one of image, audio, video, text.  This\
          \ does not specify the format of the data.\n"
        enum:
        - "image"
        - "audio"
        - "video"
        - "text"
        - "prediction"
        - "evaluation"
        - "metrics"
      format:
        type: "string"
        description: "A string representing the name of the format of the dataset.\
          \ This should be sufficient to ensure that models and transforms\n are able\
          \ to read and parse the data.\n"
      statistics:
        $ref: "#/definitions/DatasetStatistics"
      defaultGroundTruthSetReference:
        description: "A reference to the default ground truth set that is associated\
          \ with this dataset\n    \n"
        $ref: "#/definitions/ObjectReference"
    description: "Defines the location within the data lake where a dataset can be\
      \ found. It is linked to a DatasetClass\n"
    x-sml-resource: "Dataset"
    x-smlclient-verbs:
    - "create"
    - "read"
    - "update"
    - "delete"
    - "list"
    - "export"
    x-sml-scope: "project"
  DatasetStatistics:
    type: "object"
    properties:
      size:
        type: "integer"
        format: "int32"
        description: "The size (in bytes) of the dataset"
        default: 0
  ObjectReference:
    type: "object"
    properties:
      kind:
        type: "string"
        description: "The type of the object being referenced. This is often optional\
          \ as it will be inferrred by the context.\n"
      project:
        type: "string"
        description: "The project (namespace) of this object.\n"
      id:
        type: "string"
        format: "uuid"
        description: "The unique identifier of the object."
      name:
        type: "string"
        description: "The unique name of the object."
      instance:
        type: "object"
        description: "Optionally, the object reference can contain the complete object.\
          \  This is useful for unit testing where you don't want to go out to the\
          \ SRM to obtain the referenced object.\n"
        properties: {}
    description: "A reference to another declared object.  At least one of id or name\
      \ fields must be specified.\n"