swagger: '2.0'
info:
title: Model Management API
version: '3.1.0'
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/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:
?filter={ "name":"model\*", "type":"type", "description":"modelDescription", "optionalParameters":{ "entityId":"64", "entityName": "*" } }- 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.
{ 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 } ] } }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.
{ 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 } ] }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"