NAV

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

Produces

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.

Login User

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

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

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

Services Management APIs

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

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

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

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

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

Consumes

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

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

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

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

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

Consumes

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

Consumes

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

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

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

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

Session APIs

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

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

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

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

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

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

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

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

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

Consumes

Produces

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

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

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

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

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

Consumes

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

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

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

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

Session APIs

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

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

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.

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

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

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

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

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

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

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

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

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)