swagger: '2.0'
info:
  title: Model Management API
  version: '3.1.1'
  x-visibility: external
  description: >-
    Model Management is the component responsible for the storage and
    management of analytical models and solutions. Models, algorithms or other 
    scripts can be uploaded using this component to be further used by users 
    from the same tenant. 

    Users can upload new versions to the model in later requests. In case a user updates
    his model, a new version is created. All this versions can be retrieved
    using the model identifier. Also a user can update the metadata of the model by 
    creating a new version.

    When being used by other services, as in, when data needs to be completely private from any user or services, in order to prevent data to be accessed by an interractive user under the same tenant that is being impersonated with a technical user, always use a technical user that is not related to a tenant.
schemes:
  - https
basePath: /api/modelmanagement-1000001700/v3
securityDefinitions:
  amm:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
    scopes:
      plr.amm.c: upload a model or an algorithm and the corresponding metadata
      plr.amm.u: update a model or an algorithm or the metadata
      plr.amm.r: get information regarding models and metadata
      plr.amm.d: delete a model or an algorithm and the corresponding metadata
paths:
  '/models':
    get:
      tags:
        - models
      summary: Retrieves a list with all models and algorithms.
      description: >-
        Retrieves all models and algorithms uploaded by the users in the same
        tenant. The response will be an array containing information regarding
        the models. Also for each of the models the details regarding the last
        version will be present in the response
      security:
        - amm:
            - plr.amm.r
      consumes: 
        - application/json
      produces:
        - application/json
      parameters:
        - in: query
          name: pageNumber
          type: integer
          required: false
          description: Specifies the requested page index
        - in: query
          name: pageSize
          type: integer
          required: false
          format: int32
          minimum: 1
          maximum: 100
          description: Specifies the number of elements in a page
        - in: query
          name: filter
          type: string
          required: false
          description: |
            Complex filter that can filter by model name, type, description, author or fields set as optional parameters. All fields are optional.  Filters can be set as plain string or as a regular expression.
            The expected format follows:<br />
            <pre>
            ?filter={
              "name":"model\*",
              "type":"type",
              "description":"modelDescription",
              "optionalParameters":{
                 "entityId":"64",
                 "entityName": "*"
              }
            }
            </pre>
        - in: query
          name: sort
          type: string
          required: false
          enum: [asc,desc]
          default: desc
          description: >-
            Parameter used to sort the models by the *lastModified* field ascending or descending.<br />
      responses:
        '200':
          description: The list of models is retrieved
          schema:
            $ref: '#/definitions/ModelArray'
        '400':
          $ref: '#/responses/400-wrong-param'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    post:
      tags:
        - models
      summary: Uploads a model payload and the corresponding metadata.
      description: >-
        Uploads a model payload and the corresponding metadata while creating the first version of that model.
      security:
        - amm:
          - plr.amm.c
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: file
          in: formData
          type: file
          required: true
          description: The model/algorithm file
        - name: metadata
          in: formData
          required: true
          type: string
          description: |
            The details regarding what the model represents, as name, author, type, description, in JSON format (see definitions/Model and definitions/VersionDefinition)<br />
            <pre>
            {
              name: "NN - Quasi Newton",
              description: "Newton using variable matrix methods",
              type: "Zeppelin notebook",
              author: "user@siemens.com",
              version: 
              {
                number: 3.1,
                expirationDate: "2017-10-01T12:00:00.001Z",
                author: "user@siemens.com",
                creationDate: "2017-10-01T12:00:00.001Z",
                dependencies: [
                  {
                    name: "sklearn-theano",
                    type: "Python",
                    version: "1.7, 5.2.6"
                  }
                ],
                io: {
                  consumes: "CSV/XML/Parquet",
                  input: [
                    {
                      name: "t1",
                      type: "integer",
                      description: "temperature sensor value",
                      value: 5
                    }
                  ],
                  output: [
                    {
                      name: "t1",
                      type: "integer",
                      description: "temperature sensor value",
                      value: 5
                    }
                  ],
                  optionalParameters: 
                  {
                    freeFormParams: "for the author to use"
                  }
                },
                producedBy: [
                  {"951b3240-7857-11e8-adc0-fa7ae01bbebc"}
                ],
                kpi: [
                  {
                    name: "error rate",
                    value: 0.9
                  }
                ]
              }
            }</pre>
      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: Retrieves the model's textual description plus its last version details.
      description: >-
        Alows retrieving model's metadata like name, description, author, including the last version details (see definitions/Version).
      security:
        - amm:
            - plr.amm.r
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Model ID to get the information for it
          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 metadata.
      description: Allows you to update the main model details, like name, description, type
      security:
        - amm:
            - plr.amm.u
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: ID of the model which is to be updated
          required: true
          type: string
        - in: body
          name: model
          required: true
          schema:
            $ref: '#/definitions/ModelDefinition'
      responses:
        '200':
          description: The model file was updated. The new version is returned
          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: Deletes a model, including all its versions
      description: Deletes a model, all the versions and the corresponding metadata. Also, use this endpoint if needed to delete a model that has a single version available.
      security:
        - amm:
          - plr.amm.d
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: ID of the model which is to be updated
          required: true
          type: string
      responses:
        '204':
          description: The model file was deleted
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
  '/models/{modelId}/versions/last':
    get:
      tags:
        - versions
      summary: Downloads the last version payload or description of a model
      description: >-
        Retrieves the last version of a model, including its payload, depending on the accept parameter being specified: application/json will return only the last Version definition, while application/octet-stream will return the last lversion payload stored.
      security:
        - amm:
          - plr.amm.r
      consumes:
       - application/json
      produces:
        - application/json
        - application/octet-stream
      parameters:
        - name: modelId
          in: path
          description: Model ID to get the information for it
          required: true
          type: string
      responses:
        '200':
          description: >- 
            Depending on the Accept type specified it can return either the last version payload data(when application/octet-stream is used) or the last Version metadata details.
          schema:
            $ref: '#/definitions/Version'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    patch:
      tags:
        - versions
      summary: Updates the last version metadata information of a model, without allowing updates to the model payload itself
      produces:
        - application/json
      consumes:
        - application/json
      description: >- 
        Updates the last version information of a model, excluding related 
        payload if used. Information like creation date and author cannot be 
        updated. <br />
        Information regarding the model details can be updated using another 
        endpoint. The 'metadata' key in 'formData' is required.
      security:
        - amm:
          - plr.amm.u
      parameters:
        - name: modelId
          in: path
          description: The model id
          required: true
          type: string
        - in: body
          name: version
          required: true
          schema:
            $ref: '#/definitions/VersionDefinition'
      responses:
        '200':
          description: The version metadata was updated successfully. The updated version is returned.
          schema:
            $ref: '#/definitions/VersionDefinition'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    delete:
      tags:
        - versions
      summary: Deletes the last version of a model
      description: >-
        Deletes the last version of a model and its associated payload. If the version is the only 
        version of the model all the information regarding the model will be deleted.
      security:
        - amm:
          - plr.amm.d
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Id of the model which is to be deleted
          required: true
          type: string
      responses:
        '204':
          description: The last version was deleted
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
  '/models/{modelId}/versions':
    post:
      tags:
        - versions
      summary: Creates a new model version
      description: Create a new model version
      security:
        - amm:
            - plr.amm.c
      consumes:
        - multipart/form-data
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Model ID to create a new verion for
          required: true
          type: string
        - in: formData
          name: file
          type: file
          required: true
          description: The model/algorithm file
        - in: formData
          name: metadata
          required: true
          type: string
          description: |
            Version data in JSON format (See definitions/VersionDefinition)
            <pre>
            {
              number: 3.1,
              expirationDate: "2017-10-01T12:00:00.001Z",
              author: "user@siemens.com",
              creationDate: "2017-10-01T12:00:00.001Z",
              dependencies: [
                {
                  name: "sklearn-theano",
                  type: "Python",
                  version: "1.7, 5.2.6"
                }
              ],
              io: {
                consumes: "CSV/XML/Parquet",
                input: [
                  {
                    name: "t1",
                    type: "integer",
                    description: "temperature sensor value",
                    value: 5
                  }
                ],
                output: [
                  {
                    name: "t1",
                    type: "integer",
                    description: "temperature sensor value",
                    value: 5
                  }
                ],
                optionalParameters: 
                {
                  freeFormParams: "for the author to use"
                }
              },
              producedBy: [
                {"951b3240-7857-11e8-adc0-fa7ae01bbebc"}
              ],
              kpi: [
                {
                  name: "error rate",
                  value: 0.9
                }
              ]
            }
            </pre>
      responses:
        '201':
          description: The model and metadata were uploaded successfully. Returns modelID
          schema:
            $ref: '#/definitions/VersionDefinition'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    get:
      tags:
        - versions
      summary: Retrieves metadata of all versions of a model
      description: >-
        Retrieves all the versions of a model or an algorithm based on the model
        identifier. Whenever a new model file or a metadata JSON are uploaded as
        an update of an existing entry a new version of the entry is created.
        This endpoint will retrieved information regarding all the versions
        created by the users.
      security:
        - amm:
            - plr.amm.r
      consumes:
       - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Model ID to get the information for it
          required: true
          type: string
        - in: query
          name: pageNumber
          type: integer
          required: false
          description: Specifies the requested page index
        - in: query
          name: pageSize
          type: integer
          required: false
          format: int32
          minimum: 1
          maximum: 100
          description: Specifies the number of elements in a page
      responses:
        '200':
          description: The list of version of the model is retrieved
          schema:
            $ref: '#/definitions/VersionArray'
        '400':
          $ref: '#/responses/400-wrong-param'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
        '404':
          $ref: '#/responses/404-not-found'
  '/models/{modelId}/versions/{versionId}':
    get:
      tags:
        - versions
      summary: Retrieves the version payload or the version metadata
      description: Retrieves the specified version metadata or payload of a model, depending on the accept parameter being specified - application/json will return only the last Version definition, while application/octet-stream will return the stored version payload.
      security:
        - amm:
            - plr.amm.r
      consumes:
        - application/json
        - application/octet-stream
      produces:
        - application/octet-stream
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Model ID to get the information for it
          required: true
          type: string
        - name: versionId
          in: path
          description: Version ID to get the information for it
          required: true
          type: string
          format: uuid
      responses:
        '200':
          description: The version payload or version metadata is returned depending on the accept header
          schema:
            $ref: '#/definitions/Version'
        '400':
          $ref: '#/responses/400-wrong-param'
        '404':
          $ref: '#/responses/404-not-found'
        '403':
          $ref: '#/responses/403-unauth'
        '500':
          $ref: '#/responses/500-internal'
    delete:
      tags:
        - versions
      summary: Deletes the specified version of a model and the corresponding metadata
      description: >-
        Deletes a version of a model and the corresponding metadata, only if the version is not the single available version for the model.
      security:
        - amm:
            - plr.amm.d
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: modelId
          in: path
          description: Id of the model
          required: true
          type: string
        - name: versionId
          in: path
          description: The version id
          required: true
          type: string
      responses:
        '204':
          description: The version was deleted
        '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: >-
      One of the required input parameters is missing or does not follow the
      input format
    schema:
      $ref: '#/definitions/Errors'
  404-not-found:
    description: The resource or index is not found
    schema:
      $ref: '#/definitions/Errors'
  403-unauth:
    description: Forbidden - The user does not have permission for this endpoint
    schema:
      $ref: '#/definitions/Errors'
definitions:
  Model:
    type: object
    properties:
      id:
        type: string
        format: uuid
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      name:
        type: string
        example: NN - Quasi Newton
      description:
        type: string
        example: Newton using variable metrix methods
      type:
        type: string
        example: Zeppelin notebook
      author:
        type: string
        example: user@siemens.com
      lastVersion:
        $ref: '#/definitions/Version'
  ModelArray:
    type: object
    properties:
      models:
        type: array
        items:
          $ref: '#/definitions/Model'
      page:
        $ref: '#/definitions/Page'
  Version:
    type: object
    description: >-
      Returned version information. Contains the submitted version entity, as
      well as additional information provided by the system, such as user
      information, created date.
    properties:
      id:
        type: string
        format: uuid
        example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      number:
        type: number
        example: 3.1
      expirationDate:
        type: string
        format: date
        example: '2017-10-01T12:00:00.001Z'
      author:
        type: string
        example: user@siemens.com
      creationDate:
        type: string
        format: date
        example: '2017-10-01T12:00:00.001Z'
      dependencies:
        type: array
        items:
          $ref: '#/definitions/Dependency'
      io:
        $ref: '#/definitions/IO'
      producedBy:
        type: array
        items:
          type: string
          format: uuid
          example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      kpi:
        type: array
        items:
          $ref: '#/definitions/KPI'
  VersionArray:
    type: object
    properties:
      versions:
        type: array
        items:
          $ref: '#/definitions/Version'
      page:
        $ref: '#/definitions/Page'
  Dependency:
    type: object
    properties:
      name:
        type: string
        example: sklearn-theano
      type:
        type: string
        example: Python
      version:
        type: string
        example: '1.7, 5.2.6'
  KPI:
    type: object
    properties:
      name:
        type: string
        example: error rate
      value:
        type: string
        example: 0.9
  Column:
    type: object
    properties:
      name:
        type: string
        example: 't1'
      type:
        type: string
        example: integer
      description:
        type: string
        example: temperature sensor value
      value:
        type: object
        example: 5
  IO:
    type: object
    properties:
      consumes:
        type: string
        example: CSV/XML/Parquet
      input:
        type: array
        items:
          $ref: '#/definitions/Column'
      output:
        type: array
        items:
          $ref: '#/definitions/Column'
      optionalParameters:
        type: object
        description: Field which should contain any relevant metadat information which can refer to how to further process or interpret the input or output files.
  VndError:
    type: object
    properties:
      code:
        type: string
        example: mdsp.core.modelmanagement.error
        readOnly: true
      message:
        type: string
        example: Error message
        readOnly: true
      logref:
        type: string
        example: c06534d4-6f0e-11e8-adc0-fa7ae01bbebc
        readOnly: true
  Errors:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/VndError'
  Page:
    type: object
    properties:
      number:
        type: integer
        description: Number of current page.
        example: 1
      size:
        type: integer
        description: Size of the page
        example: 20
      totalPages:
        type: integer
        description: Number of the total pages
        example: 2
      totalElements:
        type: integer
        description: The total number of elements
        example: 40
  VersionDefinition:
    type: object
    properties:
      expirationDate:
        type: string
        format: date
        example: '2017-10-01T12:00:00.001Z'
      dependencies:
        type: array
        items:
          $ref: '#/definitions/Dependency'
      io:
        $ref: '#/definitions/IO'
      producedBy:
        type: array
        items:
          type: string
          format: uuid
          example: 951b3240-7857-11e8-adc0-fa7ae01bbebc
      kpi:
        type: array
        items:
          $ref: '#/definitions/KPI'
  ModelDefinition:
    type: object
    properties:
      name:
        type: string
        example: NN - Quasi Newton
      description:
        type: string
        example: Newton using variable metrix methods
      type:
        type: string
        example: "Zeppelin notebook"          
