Overview

Core APIs

Integration technology for deploying R and Python analytics inside web, desktop, mobile, and dashboard applications as well as backend systems. Turn your R or Python scripts into analytics web services, so code can be easily executed by applications running on a secure server.

The core APIs can be grouped into several categories, including: Authentication, Web Services, Sessions, Snapshots, Status, and Centralized Configuration.

External Documentation

Back to Product documentation

Version information

Version : 9.3.0

License information

License : Copyright (C) Microsoft Corporation. All rights reserved.

Swagger

Download the swagger spec file for these APIs

URI scheme

Schemes: http, https

Consumes

application/json

Produces

application/json

Authentication APIs

The `authentication` APIs provide authentication related operations and access workflow features.

All API calls must be authenticated using the `POST /login` API or through Azure Active Directory.

If you use the `POST /login` API, ML Server will issue you a bearer/access token. This bearer token is a lightweight security token that grants the “bearer” access to a protected resource, in this case, the core APIs. Once a user has been authenticated, the application must validate the user’s bearer token to ensure that authentication was successful for the intended parties. If your organization uses Azure Active Directory, then AAD will issue the token.

Path

POST /login

Description

Logs the user in.

Example Request

{
    "username": "string",
    "password": "string"
}

Example Response "application/json"

{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJSUzUxMiIsInR5cC",
    "expires_in": 3600,
    "expires_on": 1479664807,
    "refresh_token": "ScW2tnhl4Oi7ksHLj/TI"
}

Method

POST

Parameters

Type	Name	Description	Schema
body	loginRequest required	Login properties for athentication.	LoginRequest

Responses

HTTP Codes	Description	Schema
200	OK	AccessTokenResponse

Errors

401 - Unauthorized (invalid credentials)

Refresh User Access Token

Path

POST /login/refreshToken

Description

The user renews access token and refresh token.

Example Request

{
    "refreshToken": "string"
}

Example Response "application/json"

{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJSUzUxMiIsInR5cC",
    "expires_in": 3600,
    "expires_on": 1479664807,
    "refresh_token": "ScW2tnhl4Oi7ksHLj/TI"
}

Method

POST

Parameters

Type	Name	Description	Schema
body	renewTokenRequest required	Renew access token properties for athentication.	RenewTokenRequest

Responses

HTTP Codes	Description	Schema
200	OK	AccessTokenResponse

Errors

401 - Unauthorized (invalid or expired refresh token)

Delete User Access Token

Path

DELETE /login/refreshToken

Description

The user revokes a refresh token.

Example Response "application/json"

{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJSUzUxMiIsInR5cC",
    "expires_in": 3600,
    "expires_on": 1479664807,
    "refresh_token": "ScW2tnhl4Oi7ksHLj/TI"
}

Method

DELETE

Parameters

Type	Name	Description	Schema
query	refreshToken required	The refresh token to be revoked.	string

Responses

HTTP Codes	Description	Schema
200	OK	AccessTokenResponse

Errors

401 - Unauthorized (invalid or expired refresh token)

Services Management APIs

The core Web Services APIs facilitate the publishing and management of user-defined analytic web services, including:

Create
Delete
Update
List
Discover

Note: For service consumption, please see the `/api` APIs

An ML Server web service is a stateless execution on the compute node. Each web service is uniquely defined by a `name` and `version` for easy service consumption and meaningful machine-readable discovery approaches.

These RESTful APIs for web services provide programmatic access to a service's lifecycle. The APIs are straightforward, easy-to-use, and when composed together, can form the foundation for more expressive operations.

Web services can be versioned to improve the release of services for service authors and make it easier for consumers to identify the services they are calling. Service versioning is an important part of the publishing process and is designed to be flexible without naming restrictions. We highly recommend the adoption of meaningful and standard versioning conventions such as semantic versioning.

If a web service is published without a version `GET /services/{name}`, a Globally Unique Identifier (GUID) will be created as a unique reference number to represent a version. Since the GUID is not a meaningful version number, the intention is allow an author to treat the service as a development version (seen only by the author) until it is ready to be promoted and shared. From there, a more meaningful version number can be chosen during service publishing to represent a stable release.

Whenever a web service is published `POST /services/{name}/{version}` or `POST /realtime-services/{name}/{version}`, an endpoint is registered `/api/{name}/{version}`, which in turn triggers the generation of a custom Swagger-based JSON file. Learn more about consuming web services.

If you use a snapshot when developing your web service, the session snapshot information will be baked into the service API when published and available to any authenticated user consuming that web service later.

Publish the web services for the logged in user with given name and a unique version. By default, all users have permission to publish a web service. However, if your administrator has defined authorization roles, those roles determine which users can publish, update and delete web services.

Get Services

Path

GET /services

Description

Lists all the published services.

Example Response "application/json"

[
    {
        "creationTime": "2016-11-20T18:15:09.917656",
        "name": "addition",
        "version": "1.0.0",
        "description": "Addition Service.",
        "code": "result <- x + y",
        "snapshotId": "8fac71e8-92a9-4959-a679-4376e5aab20d",
        "owner": "deployruser",
        "operationId": "add",
        "inputParameterDefinitions": [
            {
                "name": "x",
                "type": "numeric"
            },
            {
                "name": "y",
                "type": "numeric"
            }
        ],
        "outputParameterDefinitions": [
            {
                "name": "result",
                "type": "numeric"
            }
        ]
    }
]

Method

GET

Responses

HTTP Codes	Description	Schema
200	OK	[ WebService ]

Errors

401 - Unauthorized

Create Service by `name`

Path

POST /services/{name}

Description

Publish the web services for the logged in user with given name and a unique version.

Example Request

{
    "snapshotId": "string",
    "code": "string",
    "description": "string",
    "operationId": "string",
    "inputParameterDefinitions": [
        "array"
    ],
    "outputParameterDefinitions": [
        "array"
    ],
    "runtimeType": "string",
    "initCode": "string",
    "outputFileNames": [
        "array"
    ]
}

Method

POST

Parameters

Type	Name	Description	Schema
path	name required	name of the published web service.	string
body	publishRequest required	Publish Web Service request details.	PublishWebServiceRequest

Responses

HTTP Codes	Description	Schema
201	Created.	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (another user owns this service and you are not authorized to publish to it)
409 - Conflict (another web service with same name and version exists. Use patch request if you want to update)

Get Service by `name`

Path

GET /services/{name}

Description

Lists all the published services with the provided name.

Example Response "application/json"

[
    {
        "name": "addition",
        "version": "1.0",
        "versionPublishedBy": "admin",
        "creationTime": "2016-11-20T18:15:09.917656",
        "snapshotId": "8fac71e8-92a9-4959-a679-4376e5aab20d",
        "runtimeType": "R",
        "initCode": "",
        "code": "result <- x + y",
        "description": "Addition Service.",
        "operationId": "add",
        "inputParameterDefinitions": [
            {
                "name": "x",
                "type": "numeric"
            },
            {
                "name": "y",
                "type": "numeric"
            }
        ],
        "outputParameterDefinitions": [
            {
                "name": "result",
                "type": "numeric"
            }
        ],
        "outputFileNames": [
            "Histogram.png"
        ],
        "myPermissionOnService": "read only"
    }
]

Method

GET

Parameters

Type	Name	Description	Schema
path	name required	name of the published web service.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ WebService ]

Errors

401 - Unauthorized

Create realtime web service by `name`

Path

POST /realtime-services/{name}

Description

Publish the realtime web services for the logged in user with given name and a unique version.

Method

POST

Parameters

Type	Name	Description	Schema
path	name required	name of the realtime web service to be published.	string
formData	description	The description of the realtime web service to be published.	string
formData	operationId	Swagger operationId/alias for the realtime web service to be published.	string
formData	model required	The binary serialized model to be used for realtime web service.	file

Responses

HTTP Codes	Description	Schema
201	Created.	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (another user owns this service and you are not authorized to publish to it)
409 - Conflict (another web service with same name and version exists. Use patch request if you want to update)

Consumes

multipart/form-data

Create Service by `name` and `version`

Path

POST /services/{name}/{version}

Description

Publish the web service for the logged in user with given name and version.

Example Request

{
    "snapshotId": "string",
    "code": "string",
    "description": "string",
    "operationId": "string",
    "inputParameterDefinitions": [
        "array"
    ],
    "outputParameterDefinitions": [
        "array"
    ],
    "runtimeType": "string",
    "initCode": "string",
    "outputFileNames": [
        "array"
    ]
}

Method

POST

Parameters

Type	Name	Description	Schema
path	name required	name of the published web service.	string
path	version required	version of the published web service.	string
body	publishRequest required	Publish Service request details.	PublishWebServiceRequest

Responses

HTTP Codes	Description	Schema
201	Created.	string

Errors

400 - Bad request
401 - Unauthorized
403 - Forbidden (another web service with same name and version exists. Use patch request if you want to update)

Patch Service

Path

PATCH /services/{name}/{version}

Description

Updates the published service.

Example Request

{
    "snapshotId": "string",
    "code": "string",
    "description": "string",
    "operationId": "string",
    "inputParameterDefinitions": [
        "array"
    ],
    "outputParameterDefinitions": [
        "array"
    ],
    "runtimeType": "string",
    "initCode": "string",
    "outputFileNames": [
        "array"
    ]
}

Method

PATCH

Parameters

Type	Name	Description	Schema
path	name required	The name of the published web service.	string
path	version required	The version of the published web service.	string
body	patchRequest required	Publish Web Service request details.	PublishWebServiceRequest

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (service with that name and version is owned by a different user, only the owner can update it)
404 - Not Found (web service not found)

Get Service by `name` and `version`

Path

GET /services/{name}/{version}

Description

Lists all the published services with the provided name and version.

Example Response "application/json"

{
    "name": "addition",
    "version": "1.0",
    "versionPublishedBy": "admin",
    "creationTime": "2016-11-20T18:15:09.917656",
    "snapshotId": "8fac71e8-92a9-4959-a679-4376e5aab20d",
    "runtimeType": "R",
    "initCode": "",
    "code": "result <- x + y",
    "description": "Addition Service.",
    "operationId": "add",
    "inputParameterDefinitions": [
        {
            "name": "x",
            "type": "numeric"
        },
        {
            "name": "y",
            "type": "numeric"
        }
    ],
    "outputParameterDefinitions": [
        {
            "name": "result",
            "type": "numeric"
        }
    ],
    "outputFileNames": [
        "Histogram.png"
    ],
    "myPermissionOnService": "read only"
}

Method

GET

Parameters

Type	Name	Description	Schema
path	name required	The name of the published web service.	string
path	version required	The version of the published web service.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ WebService ]

Errors

401 - Unauthorized
404 - Not Found (session not found)

Delete Service

Path

DELETE /services/{name}/{version}

Description

Deletes the published web service for the logged in user.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	name required	The name of the published web service.	string
path	version required	The version of the published web service.	string

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

401 - Unauthorized
403 - Forbidden (service with that name and version is owned by a different user, only the owner can delete it guid)
404 - Not Found (service not found)

Create realtime web service by `name` and `version`.

Path

POST /realtime-services/{name}/{version}

Description

Publish the realtime web services for the logged in user with given name and given version.

Method

POST

Parameters

Type	Name	Description	Schema
path	name required	The name of the realtime web service to be published.	string
path	version required	The version of the realtime web service to be published.	string
formData	description	The description of the realtime web service to be published.	string
formData	operationId	Swagger operationId/alias for the realtime web service to be published.	string
formData	model required	The binary serialized model to be used for realtime web service.	file

Responses

HTTP Codes	Description	Schema
201	Created.	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (another user owns this service and you are not authorized to publish to it)
409 - Conflict (another web service with same name and version exists. Use patch request if you want to update)

Consumes

multipart/form-data

Patch realtime web service

Path

PATCH /realtime-services/{name}/{version}

Description

Updates the published realtime web service.

Method

PATCH

Parameters

Type	Name	Description	Schema
path	name required	Name of the published realtime web service	string
path	version required	Version of the published realtime web service	string
formData	description	The description of the realtime web service to be published.	string
formData	operationId	Swagger operationId/alias for the realtime web service to be published.	string
formData	model	The binary serialized model to be used for realtime web service.	file

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (service with that name and version is owned by a different user, only the owner can update it)
404 - Not Found (web service not found)

Consumes

multipart/form-data

Create or update dedicated pool for web service

Path

POST /services/{name}/{version}/pool

Description

Create or update a dedicated pool for service on all compute nodes.

Example Request

{
    "InitialPoolSize": "integer",
    "MaxPoolSize": "integer"
}

Method

POST

Parameters

Type	Name	Description	Schema
path	name required	name of the web service.	string
path	version required	version of the web service.	string
body	createOrUpdateServicePoolRequest required	Create or update Service pool request details.	CreateOrUpdateServicePoolRequest

Responses

HTTP Codes	Description	Schema
200	Created.	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (you are not authorized to create or update service pools))

Delete dedicated pool for Service

Path

DELETE /services/{name}/{version}/pool

Description

Delete a dedicated pool for service on all compute nodes.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	name required	name of the web service.	string
path	version required	version of the web service.	string

Responses

HTTP Codes	Description	Schema
200	Deleted.	string

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (you are not authorized to create or update service pools))

Get status of the dedicated pool for service.

Path

GET /services/{name}/{version}/pool

Description

List status of the dedicated pools for the published web service on all ComputeNodes.

Example Response "application/json"

[
    {
        "ComputeNodeEndpoint": "http://localhost:12800",
        "Status": "Success"
    }
]

Method

GET

Parameters

Type	Name	Description	Schema
path	name required	name of the web service.	string
path	version required	version of the web service.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ ServicePoolStatusResponse ]

Errors

401 - Unauthorized

Service Consumption APIs

The `service api` APIs provide operations for obtaining the `swagger` service holding and capabilities for a specific published web service. From this, analytic web service consumption can take place.

Get API Swagger

Path

GET /api/{name}/{version}/swagger.json

Description

Returns a Swagger swagger.json describing a published web service's API capabilities.

Example Response "text/plain"

"The service's `swagger.json` document."

Method

GET

Parameters

Type	Name	Description	Schema
path	name required	The name of the published web service.	string
path	version required	The version of the published web service.	string

Responses

HTTP Codes	Description	Schema
200	OK	SwaggerJsonResponse

Errors

400 - Bad request
401 - Unauthorized
404 - Not Found (Web service not found)

Session APIs

The `sessions` APIs provide functionality for session management, which can be divided into the following groups:

`Session lifecycle APIs` help manage the session lifecycle.
`Session workspace APIs` help manage the objects in your workspace.
`Session working directory APIs` help manage the files in your workspace.
`Session snapshot APIs` help create and manage session snapshots. More snapshot APIs are covered in the next section.

A session is an interactive stateful session that is run in an R or Python shell on the compute node. A session is managed by ML Server on behalf of the application.

Create Session

Path

POST /sessions

Description

Create a new session.

Example Request

{
    "name": "string",
    "snapshotId": "string",
    "runtimeType": "string"
}

Example Response "application/json"

{
    "sessionId": "85b1ecd8-f5a5-42ce-87f3-5b7be97665ae"
}

Method

POST

Parameters

Type	Name	Description	Schema
body	createSessionRequest required	Properties of the new session.	CreateSessionRequest

Responses

HTTP Codes	Description	Schema
201	Created. Returns the id of the newly created session.	CreateSessionResponse

Errors

401 - Unauthorized
404 - Not Found (session not found)

Get Sessions

Path

GET /sessions

Description

Lists all existing sessions for the current user.

Example Response "application/json"

[
    {
        "id": "e052a7f7-8fcd-40b9-b9b8-d351acd44444",
        "name": "mPheQrfoO0LmbLZ",
        "owner": "deployruser"
    },
    {
        "id": "l0dfsddf-4gjd-40b9-b9b8-sdf98yh99999",
        "name": "mPheQrfoO0LmbLZ",
        "owner": "sean"
    }
]

Method

GET

Responses

HTTP Codes	Description	Schema
200	The sessions for the current user.	[ Session ]

Errors

401 - Unauthorized

Execute Code

Path

POST /sessions/{id}/execute

Description

Executes code in the context of a specific session.

Example Request

{
    "code": "string",
    "inputParameters": [
        "array"
    ],
    "outputParameters": [
        "array"
    ]
}

Example Response "application/json"

{
    "success": true,
    "errorMessage": "",
    "outputParameters": [],
    "consoleOutput": "[1] 5\r\n",
    "changedFiles": []
}

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
body	executeRequest required	code that needs to be executed	ExecuteRequest

Responses

HTTP Codes	Description	Schema
200	OK	ExecuteResponse

Errors

401 - Unauthorized
404 - Not Found (session not found)

Delete Session

Path

DELETE /sessions/{id}

Description

Close a session and releases all it's associated resources.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	id required	Id of the session to delete.	string

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

401 - Unauthorized
404 - Not Found (session not found)

Delete Session by `force`

Path

DELETE /sessions/{id}/force

Description

Attempt to kill a session and releases all it's associated resources.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	id required	Id of the session to delete.	string

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

401 - Unauthorized
404 - Not Found (session not found)

Get Console Output

Path

GET /sessions/{id}/console-output

Description

Returns the console output for the current or last execution.

Example Response "application/json"

{
    "consoleOutput": "[1] 5\r\n"
}

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string

Responses

HTTP Codes	Description	Schema
200	OK	ConsoleOutputResponse

Errors

401 - Unauthorized
404 - Not Found (session not found)

Get History

Path

GET /sessions/{id}/history

Description

Lists all history for a specific session.

Example Response "application/json"

[
    "model <- glm(formula = am ~ hp + wt, data = mtcars, family = binomial)",
    "manualTransmission <- function(hp, wt) { \r\n newdata <- data.frame(hp = hp, wt = wt) \r\npredict(model, newdata, type = \"response\") \r\n}",
    "print(manualTransmission(120, 2.8))"
]

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ string ]

Errors

401 - Unauthorized
404 - Not Found (session not found)

Load File

Path

POST /sessions/{id}/files

Description

Loads a file into the session working directory. The uploaded file name is extracted from the file and if another file with the same name already exists in the working directory, the file will be overwritten.

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
formData	file required	The file to be uploaded to the workspace.	file

Responses

HTTP Codes	Description	Schema
201	Created	N/A

Errors

401 - Unauthorized
404 - Not Found (session not found)

Consumes

multipart/form-data

Produces

text/plain

Get Files

Path

GET /sessions/{id}/files

Description

Lists all files of a specific session.

Example Response "application/json"

[
    "statscore.csv",
    "hist.png",
    "notes.Rmd"
]

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ string ]

Errors

401 - Unauthorized
404 - Not Found (session not found)

Get File

Path

GET /sessions/{id}/files/{fileName}

Description

Downloads a file from a session as a stream.

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	fileName required	Name of the file.	string

Responses

HTTP Codes	Description	Schema
200	OK	file

Errors

401 - Unauthorized
404 - Not Found (session not found)

Delete File

Path

DELETE /sessions/{id}/files/{fileName}

Description

Delete a file from a session's working directory.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	fileName required	Name of the file.	string

Responses

HTTP Codes	Description	Schema
200	File is deleted	N/A

Errors

401 - Unauthorized
404 - Not Found (session not found)

Get Workspace Object Names

Path

GET /sessions/{id}/workspace

Description

Lists all object names of a specific session.

Example Response "application/json"

[
    "model",
    "manualTransmission",
    "am.glm",
    "newdata"
]

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string

Responses

HTTP Codes	Description	Schema
200	OK	[ string ]

Errors

401 - Unauthorized
404 - Not Found (session not found)
410 - Gone (once live session is now gone)

Create Workspace Object

Path

POST /sessions/{id}/workspace/{objectName}

Description

Upload a serialized object into the session.

Example Request

binary

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	objectName required	Name of the object.	string
body	serializedObject required	The binary file that contains a serialized object to be uploaded. The binary file `Content-Type` should be `application/octet-stream`.	string

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

401 - Unauthorized
404 - Not Found (session not found)

Consumes

application/octet-stream

Get Workspace Object

Path

GET /sessions/{id}/workspace/{objectName}

Description

Returns an object from a session. For the R runtime, the object is serialized as a .RData file stream. For the Python runtime, the object is serialized as a .dill file stream.

Important Python objects are not guaranteed to be compatible with versions other than Python 3.5.

Example Response "application/octet-stream"

"[1] 5b 7b 22 63 72 65 61 74 69 6f 6e 54 69 6d 65 22 3a 22 32 30 31 36 2d 31 31 2d [27] 32 30 54 31 39 3a 35 30 3a 34 39 2e 37 35 32 37 36 37 36 22 2c 22 6e 61 6d 65"

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	objectName required	Name of the R or Python object.	string

Responses

HTTP Codes	Description	Schema
200	OK	file

Errors

401 - Unauthorized
404 - Not Found (session or object not found)

Delete Workspace Object

Path

DELETE /sessions/{id}/workspace/{objectName}

Description

Delete an object from a session.

Method

DELETE

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	objectName required	Name of the object.	string

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

401 - Unauthorized
404 - Not Found (session or object not found)

Snapshot APIs

These APIs provide different operations to access and manage workspace snapshots. A snapshot is a prepared environment image of an R or Python session saved to Microsoft ML Server. A snapshot also includes the session's packages, objects and data files.

For optimal performance, consider the size of the snapshot carefully especially when publishing a service. Before creating a snapshot, ensure that you keep only those workspace objects you need and purge the rest. And, in the event that you only need a single object, consider passing that object alone itself instead of using a snapshot.

A snapshot can be loaded into any subsequent remote session for the user who created it. For example, suppose you want to execute a script that needs three R packages, a reference data file, and a model object. Instead of loading these items each time you want to execute the script, create a snapshot of an session containing them. Then, you can save time later by loading this snapshot using its ID to get the session contents exactly as they were at the time the snapshot was created.

Create Snapshot

Path

POST /sessions/{id}/snapshot

Description

Create a snapshot from session by saving the workspace and all files in the working directory into zip file, the return value will be the created snapshot Id.

Example Request

{
    "name": "string"
}

Example Response "application/json"

{
    "snapshotId": "8fac71e8-92a9-4959-a679-4376e5aab20d"
}

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
body	createSnapshotRequest required	Properties of the new snapshot.	CreateSnapshotRequest

Responses

HTTP Codes	Description	Schema
201	Created	CreateSnapshotResponse

Errors

401 - Unauthorized
404 - Not Found (session not found)

Load Snapshot

Path

POST /sessions/{id}/loadsnapshot/{snapshotId}

Description

Loads a snapshot into session by merging the workspace of the saved snapshot and target session. It will override the files in the working directory as well.

Note - You can only load R snapshots to R session and Python snapshots to a Python session.

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session.	string
path	snapshotId required	Id of the saved snapshot.	string

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

401 - Unauthorized
404 - Not Found (session or snapshot not found)

Session APIs

The `sessions` APIs provide functionality for session management, which can be divided into the following groups:

`Session lifecycle APIs` help manage the session lifecycle.
`Session workspace APIs` help manage the objects in your workspace.
`Session working directory APIs` help manage the files in your workspace.
`Session snapshot APIs` help create and manage session snapshots. More snapshot APIs are covered in the next section.

A session is an interactive stateful session that is run in an R or Python shell on the compute node. A session is managed by ML Server on behalf of the application.

Cancel Session

Path

POST /sessions/{id}/cancel

Description

Cancel a session by aborting the current execution operation, afterwards the session will be alive and ready to accept any calls. Cancel session is not guaranteed to interrupt the execution

Method

POST

Parameters

Type	Name	Description	Schema
path	id required	Id of the session to cancel.	string

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

401 - Unauthorized
404 - Not Found (session not found)

Snapshot APIs

Get Snapshots

Path

GET /snapshots

Description

List all the snapshots for the current user and display some info such as Id, display name, creation time, zip file size and owner for this snapshot.

Method

GET

Responses

HTTP Codes	Description	Schema
200	OK	[ Snapshot ]

Errors

401 - Unauthorized

Get Snapshot

Path

GET /snapshots/{id}

Description

Get the snapshot content as zip file stream (zip file containing the working directory files and the workspace file)

Method

GET

Parameters

Type	Name	Description	Schema
path	id required	Id of the snapshot.	string

Responses

HTTP Codes	Description	Schema
200	OK	file

Errors

401 - Unauthorized
404 - Not Found (snapshot not found)

Delete Snapshot

Path

DELETE /snapshots/{id}

Description

Delete a snapshot permanently and also it's content (zip file containing the working directory files and the workspace file)

Method

DELETE

Parameters

Type	Name	Description	Schema
path	id required	Id of the snapshot.	string

Responses

HTTP Codes	Description	Schema
200	OK	string

Errors

401 - Unauthorized
404 - Not Found (snapshot not found)

Status APIs

You can retrieve the 'raw details' on the health of the system using the `GET /status` API call.

Get Status

Path

GET /status

Description

Gets the current health of the system.

Example Response "application/json"

{
    "statusCode": "pass",
    "components": {
        "backends": {
            "statusCode": "pass",
            "components": {
                "http://localhost:12805/": {
                    "statusCode": "pass",
                    "components": null,
                    "details": {
                        "rMaxPoolSize": 80,
                        "rActiveShellCount": 2,
                        "rCurrentPoolSize": 5,
                        "rCanOpenShell": "True",
                        "pythonMaxPoolSize": 80,
                        "pythonActiveShellCount": 0,
                        "pythonCurrentPoolSize": 5,
                        "pythonCanOpenShell": "True",
                        "apiVersion": "1.0",
                        "logPath": "C:\\Program Files\\Microsoft\\ML Server\\R_SERVER\\o16n\\Microsoft.RServer.ComputeNode\\logs"
                    }
                }
            },
            "details": {}
        },
        "authentication": {
            "statusCode": "pass",
            "components": {
                "azureActiveDirectory": {
                    "statusCode": "pass",
                    "components": null,
                    "details": {
                        "authority": "https://login.windows.net/microsoft.com",
                        "audience": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                    }
                }
            },
            "details": {}
        },
        "database": {
            "statusCode": "pass",
            "components": null,
            "details": {
                "type": "sqlite",
                "name": "main",
                "state": "Open"
            }
        }
    },
    "details": {
        "logPath": "C:\\Program Files\\Microsoft\\ML Server\\R_SERVER\\o16n\\Microsoft.RServer.WebNode\\logs"
    }
}

Method

GET

Responses

HTTP Codes	Description	Schema
200	OK	StatusResponse

Errors

401 - Unauthorized
500 - Internal Server Error (server cannot report its own status)

Centralized Configuration APIs

These APIs manage the configuration shared between all the web nodes. Changes to web node configuration made via the APIs are reflected across all web nodes.
Currently, the APIs allow for the compute node URIs to be viewed or changed view the GetComputeNodes, SetComputeNodes, AddComputeNode, and RemoveComputeNode APIs.

Get Compute Nodes

Path

GET /computenodes

Description

Lists all existing compute node uris.

Method

GET

Responses

HTTP Codes	Description	Schema
200	OK	GetComputeNodesResponse

Errors

401 - Unauthorized

Set Compute Nodes

Path

POST /computenodes

Description

Sets entire list of compute node uris, overriding previous entries.

Example Request

{
    "entries": [
        "array"
    ]
}

Method

POST

Parameters

Type	Name	Description	Schema
body	entries required	List of URIs or Ranges to set. Will override previous entries.	UpdateComputeNodesRequest

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (user does not have admin role)

Add Compute Node

Path

PUT /computenodes

Description

Add Compute Node URIs or Ranges to list.

Example Request

{
    "entries": [
        "array"
    ]
}

Method

PUT

Parameters

Type	Name	Description	Schema
body	entries required	List of URIs or Ranges to be added.	UpdateComputeNodesRequest

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (user does not have admin role)

Remove Compute Node

Path

DELETE /computenodes

Description

Remove Compute Node URIs or Ranges from list.

Example Request

{
    "entries": [
        "array"
    ]
}

Method

DELETE

Parameters

Type	Name	Description	Schema
body	entries required	List of URIs or Ranges to be removed.	UpdateComputeNodesRequest

Responses

HTTP Codes	Description	Schema
200	OK	N/A

Errors

400 - Bad Request
401 - Unauthorized
403 - Forbidden (user does not have admin role)

Schema Definitions

Session

PROPERTIES

id: string
Unique identifier representing the session.

name: string
Name of the session.

owner: string
Owner of the session.

runtimeType: string enum [R, Python]
Type of the runtime.

UpdateComputeNodesRequest

PROPERTIES

entries: string

GetComputeNodesResponse

PROPERTIES

computeNodes: string

CreateSessionRequest

PROPERTIES

name: string
Name of the session. Optional

snapshotId: string
Id of the snapshot to be loaded into the new created session. Optional

runtimeType: string enum [R, Python]
Type of the runtime. Optional [Default R]

CreateSessionResponse

PROPERTIES

sessionId: string
Id of the newly created session.

Snapshot

PROPERTIES

id: string
Unique identifier representing the snapshot.

name: string
Name of the snapshot.

owner: string
Owner of the snapshot.

creationTime: string
Creation time of the snapshot.

contentSize: integer
Size of the zip file of the snapshot.

CreateSnapshotRequest

PROPERTIES

name: string
Name of the snapshot. Optional

CreateSnapshotResponse

PROPERTIES

snapshotId: string
Id of the created snapshot.

ExecuteRequest

PROPERTIES

code: string
code to execute. Required

inputParameters: WorkspaceObject

outputParameters: string

ExecuteResponse

PROPERTIES

success: boolean
The operation was successful.

errorMessage: string
Errors returned by the execution.

outputParameters: WorkspaceObject

consoleOutput: string
The console output of the execution.

changedFiles: string

WorkspaceObject

PROPERTIES

name: string
The name of the workspace object.

value: object

ParameterDefinition

PROPERTIES

name: string
The name of the parameter object.

type: string enum [logical, numeric, integer, character, vector, matrix, data.frame]
The type of the parameter object.

LoginRequest

PROPERTIES

username: string
The name of the user. Required

password: string
The password of the user. Required

RenewTokenRequest

PROPERTIES

refreshToken: string
A currently valid refresh token. Required

AccessTokenResponse

PROPERTIES

token_type: string

access_token: string

expires_on: string

refresh_token: string

Error

PROPERTIES

message: string

link: string

exceptionType: string

PublishWebServiceRequest

PROPERTIES

snapshotId: string
ID of the snapshot to be used for service. Optional

code: string
Code to execute. Specific to the runtime type. Required

description: string
Description for the web service. Optional

operationId: string
Swagger operationId/alias for web service. Optional

inputParameterDefinitions: ParameterDefinition

outputParameterDefinitions: ParameterDefinition

runtimeType: string enum [R, Python]
Type of the runtime. Optional [Default R]

initCode: string
Code that runs before each request. Specific to the runtime type. Optional

outputFileNames: string

CreateOrUpdateServicePoolRequest

PROPERTIES

InitialPoolSize: integer
Initial size of the dedicated pool. Must be equal to or greater than 0. Also must be equal to or smaller than MaxPoolSize.Optional

MaxPoolSize: integer
Maximum size of the dedicated pool. Must be equal to or greter than 0. Also must be equal to or greater than InitialPoolSize.Optional

WebService

PROPERTIES

name: string
Name of the published service.

version: string
Version of the Published Service.

versionPublishedBy: string
Username of the user who published this version of the published web-service.

creationTime: string
Creation time for the service.

snapshotId: string
ID of the snapshot to be used for service.

runtimeType: string enum [R, Python, Realtime]
Type of the runtime.

initCode: string
Code to execute before the request. Specific to the runtime type.

code: string
Code to execute. Specific to the runtime type.

description: string
Description of the web service.

operationId: string
Swagger operationId/alias for the web service.

inputParameterDefinitions: ParameterDefinition

outputParameterDefinitions: ParameterDefinition

outputFileNames: string

myPermissionOnService: string
User's permission for this service, it is either 'read/write' or 'read only'.'read/write' means that the user can update/delete this service and 'read only' means that the user can consume it only.

ConsoleOutputResponse

PROPERTIES

consoleOutput: string
Console output of the current or last execution

StatusResponse

PROPERTIES

statusCode: string enum [fail, pass, warn]
Health of the system.

details: object

components: StatusResponse

SwaggerJsonResponse

PROPERTIES

ServicePoolStatusResponse

PROPERTIES

ComputeNodeEndpoint: string
The Uri address of the Computenode.

Status: string enum [Success, Pending, NotFound]
The status of the dedicate pool on the ComputeNode.

Error Codes

APIs use the following generalized error codes:

Code	Message	Meaning
400	Bad Request	The request was unacceptable, often due to missing a required parameter
401	Unauthorized	No valid API key provided
402	Request Failed	The parameters were valid but the request failed
403	Forbidden	The server understood the request, but is refusing to fulfill it
404	Not Found	The requested resource doesn't exist
409	Conflict	The request conflicts with another request
410	Gone	The request could not be completed due to a conflict with the current state of the resource
500	Internal Server Error	Something went wrong on the server end. (These are rare)

Overview

External Documentation

Version information

License information

Swagger

URI scheme

Consumes

Produces

Authentication APIs

Login User

Path

Description

Method

Parameters

Responses

Errors

Refresh User Access Token

Path

Description

Method

Parameters

Responses

Errors

Delete User Access Token

Path

Description

Method

Parameters

Responses

Errors

Services Management APIs

Get Services

Path

Description

Method

Responses

Errors

Create Service by name

Path

Description

Method

Parameters

Responses

Errors

Get Service by name

Path

Description

Method

Parameters

Responses

Errors

Create realtime web service by name

Path

Description

Method

Parameters

Responses

Errors

Consumes

Create Service by name and version

Path

Description

Method

Parameters

Responses

Errors

Patch Service

Path

Description

Method

Parameters

Responses

Errors

Get Service by name and version

Path

Description

Method

Parameters

Responses

Errors

Create Service by `name`

Get Service by `name`

Create realtime web service by `name`

Create Service by `name` and `version`

Get Service by `name` and `version`

Create realtime web service by `name` and `version`.