Model Management Service– Samples¶
The samples below exemplify how to use the provided endpoints.
Note
For avoiding confusions with JSON syntax, placeholders are indicated using angle brackets instead of curly brackets in the following samples.
Note
All requests must contain authorization headers in one of the two forms:
X-XSRF-TOKEN: `<xsrf-token>`
or
Authorization: Bearer `<authorization-token>`
Uploading a Model with Version Metadata and a Binary File¶
Request:
POST /api/modelmanagement/v3/models
Provide the following content for the metadata key of the form-data:
{
"name": "Model 1",
"description": "Model 1",
"type": "Protobuf file",
"lastVersion": {
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "2.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1": "value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
}
The file key of the form-data must contain the payload of the model's binary file.
Response:
{
"id": "<new_model_id>",
"name": "Model 1",
"description": "Model 1",
"type": "PDF File",
"author": "creator@siemens.com",
"lastVersion": {
"id": "<new_version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "2.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
}
Uploading a New Version of a Model¶
Request:
POST /api/modelmanagement/v3/models/<model_id>/versions
Provide the following content for the metadata key of the form-data:
{
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
The file key of the form-data must contain the payload of the model's binary file.
Response:
{
"id": "<new_version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
Updating a Model¶
The PATCH request is used to selectively update specific attributes of a model's metadata and its version. When updating array fields, the entire array must be provided as an input, because the service completely replaces the respective arrays.
For example, the entire list of items must be provided, when updating the dependencies field. The Model Management service takes the items provided in the request and replaces the stored attribute entirely. This also applies to the io, produced_by and kpi fields.
Except for author, creationDate, and id, any field of the model can be updated, including its version (attribute lastVersion).
Note that, the number attribute is automatically incremented, if not provided with a higher version than what is stored.
Request:
PATCH /api/modelmanagement/v3/models/<model_id>
Provide the following content for the metadata key of the form-data:
{
"name":"new model name",
"lastVersion":
{
"number": 1.4,
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
},
{
"name": "newVarName",
"type": "string",
"description": "description for newVarName, e.g. path",
"value": "/usr/lib/zeppelin/some.c"
}
]
},
}
}
The file key of the form-data must contain the payload of the model's binary file.
Response:
{
"id": "<model_id>",
"name":"new model name",
"description": "old model description",
"author": "user@siemens.com",
"lastVersion":
{
"id": "<version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
},
{
"name": "newVarName",
"type": "string",
"description": "description for newVarName, e.g. path",
"value": "/usr/lib/zeppelin/some.c"
}
],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
}
Updating the Last Version of a Model¶
Request:
PATCH /api/modelmanagement/v3/models/<model_id>/versions/last
Any field of the version can be updated, except for author, creationDate and id.
Provide the following content for the metadata key of the form-data:
{
"number": 1.2,
"expirationDate": "2019-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
},
{
"name": "numpy",
"type": "Python",
"version": "1.15"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
The file key of the form-data must contain the payload of the model's binary file.
Response:
{
"id": "<version_id>",
"number": 1.2,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
},
{
"name": "numpy",
"type": "Python",
"version": "1.15"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
Listing Available Models¶
This lists all available models, along with their last version only.
Request:
GET /api/modelmanagement/v3/models
Accept: `application/json`
Response:
{[
{
"id": "<model1_id>",
"name": "some model 1",
"description": "Some Model 1",
"type": "PB file",
"author": "user@siemens.com",
"lastVersion": {
"id": "<version1_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
},
{
"id": "<model2_id>",
"name": "some model 2",
"description": "Some Model 2",
"type": "JSON file",
"author": "user@siemens.com",
"lastVersion": {
"id": "<version1_id>",
"number": 1.0,
"expirationDate": "2019-11-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<yet_another_existing_model_id>, <and_another_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
}],
"page": {
"number": 0,
"size": 14,
"totalPages": 1,
"totalElements": 14
}
}
Obtaining a Model's Metadata¶
Request:
GET /api/modelmanagemen/v3/models/<model_id>`
Response:
{
"id": "<model_id>",
"name": "some_model",
"description": "Model 1",
"type": "PDF File",
"author": "creator@siemens.com",
"lastVersion": {
"id": "<version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": [<existing_model_id>, <other_existing_model_id>],
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
}
Downloading a Model's Metadata or Last Version's Payload¶
This request can be used to download either the metadata or the payload of the last version based on the Content-Type header. If the Content-Type is specified as application/octet-stream, the service returns the last version's payload. In this sample the Content-Type is specified as application/json, for which the last version's metadata is returned:
GET /api/modelmanagement/v3/<model_id>/versions/<version_id> HTTP/1.1
Content-Type: `application/json`
Response:
{
"id": "<version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": "[<existing_model_id>, <other_existing_model_id>]",
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
Obtaining the Metadata or Payload of a Specific Version of a Model¶
This request can be used to download either the metadata or the payload of the specific version of a model. If the Content-Type header is specified as application/octet-stream, the service returns the specified version's payload. In this sample the Content-Type is specified as application/json, for which the service returns the metadata of the model's specified version.
GET /api/modelmanagement/v3/models/<model_id>/versions/<version_id> HTTP/1.1
Content-Type: `application/json`
Response:
{
"id": "<version_id>",
"number": 1.0,
"expirationDate": "2019-10-01T12:00:00.001",
"author": "user@siemens.com",
"creationDate": "2018-10-01T12:00:00.001",
"dependencies": [{
"name": "sklearn-theano",
"type": "Python",
"version": "1.7"
}],
"io": {
"consumes": "CSV",
"input": [{
"name": "variablename1",
"type": "integer",
"description": "description for variablename1",
"value": 5
}],
"output": [{
"name": "outputname1",
"type": "integer",
"description": "description for outputname1",
"value": null
}],
"optionalParameters": {
"freeFormParams": "for the author to use",
"param1":"value1"
}
},
"producedBy": [<existing_model_id>, <other_existing_model_id>],
"kpi": [{
"name": "error rate",
"value": 0.9
}]
}
Deleting a Model¶
When deleting a model, all of its related versions are deleted successively. Versions are deleted from smallest to largest version number. After deleting all associated metadata and payload files, the model itself is deleted.
DELETE /api/modelmanagement/v3/models/<model_id>`
Response:
Status: 204 - No content
Deleting the Last Version of a Model¶
DELETE /api/modelmanagement/v3/models/<model_id>/versions/last
Response:
Status: 204 - No content
Deleting a Specific Version of a Model¶
Both the model ID and the version ID must be specified for this service.
DELETE /api/modelmanagement/v3/models/<model_id>/versions/<version_id>
Response:
Status: 204 - No content
Managing Docker images¶
Through this API we are now providing Docker image management support. All the operations available for regular (file based) payloads are also available for Docker images (type='Docker Image).
Uploading a Model with a previously uploaded Docker image¶
Once the Docker image has been uploaded the repository that hosts the image needs its metadata associated with an AMM entity. For that, the following needs to be accomplished:
POST /api/modelmanagement/v3/models
Provide the following content for the metadata key of the form-data:
{
"name": "My Docker Model 1",
"description": "Docker image 1",
"type": "Docker Image",
"lastVersion": {
"expirationDate": "2025-10-01T12:00:00.001"
}
}
In this request, the number attribute is not required for type="Docker Image" since this is extracted from the URI's tag. The provided image tag will be filling the number attribute automatically, hence why this is not required.
The uri key of the form-data must contain the URI repository of the Docker image, plus the desired tag; if no tag is specified, then latest is being assumed. The repository URI form needs to match the URI:tag format. If latest tag or the specified tag does not exist in the repository, the request will fail.
Response:
{
"id": "<new_model_id>",
"name": "My Docker Model 1",
"description": "Docker image 1",
"type": "Docker Image",
"lastVersion": {
"id": "<new_version_id>",
"uri": "<URI-of-the-repository>:<>"
}
}
Uploading a Version for a previously uploaded Docker image¶
You can upload Docker images at your own pace, and define as many versions(tags) as you need. But in order to make use of that new image tag in AMM you need to associate its URI and tag with the Version metadata. For that, you need to follow identical steps like in the Version creation, but you also need to specify the Docker image URI and tag.
POST /api/modelmanagement/v3/models/<model_id>/versions
Provide the following Version content for the metadata key of the form-data:
{
"expirationDate": "2025-10-01T12:00:00.001"
}
In this request, the number attribute is not required for type="Docker Image" models, since this is extracted from the URI's tag. The provided image tag will be filling the number attribute automatically, hence why this is not required.
Also, the uri key of the form-data must contain the URI repository of the Docker image, plus the desired tag; if no tag is specified, then latest is being assumed. The repository URI form needs to match the URI:tag format. If latest tag or the specified tag does not exist in the repository, then the request will fail.
Response:
{
"id": "<version_id>",
"number": "<myRemoteTag1.0>",
"expirationDate": "2024-10-01T12:00:00.001",
"creationDate": "2021-01-07T09:49:47.704",
"lastModified": "2021-01-07T09:49:47.704",
"author": "myuser@company.com",
"uri": "<URI-of-the-repository>:<myRemoteTag1.0>"
}
Obtain temporary tokens for Docker operations¶
Simply perform a GET request on this endpoint:
GET /api/modelmanagement/v3/repositories/getAccessToken HTTP/1.1
Content-Type: `application/json`
and the response is in the following form:
{
"credentials": {
"user": "<provider-user>",
"password": "<password-for-repository-access>",
"registry": "<url-of-the-registry>"
},
"uri": "<URI-of-the-repository>",
"providerCredentials": {
"accessKey": "<key>",
"secret": "<secret>",
"sessionToken": "<temporary-session-token>"
},
"expirationTime": "2019-01-07T07:52:34.000"
}
Uploading a new docker image¶
Using the temporary token for a Docker operation that can be obtained using GET /api/modelmanagement/v3/repositories/getAccessToken, you can upload a Docker image to this AMM repository by following these steps:
- Log in with your Docker CLI by
docker login -u <provider-user> -p <password-for-repository-access> <url-of-the-registry> - Tag your local image with the provided repository URI
docker tag localimage:vTag1.0 <URI-of-the-repository>:<myRemoteTag1.0> - Upload the docker image in the repository
docker push <URI-of-the-repository>:myRemoteTag1.0and wait for the upload to complete - Associate AMM metadata with the newly image by creating a regular AMM model where you also specify the new repository as shown in Uploading a Model with a previously uploaded Docker image