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.
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)
            {
              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.
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)
            {
              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"