RESTful API

The RESTful API uses the request-response model of the Hypertext Transfer Protocol (HTTP) for communication with MATLAB^® Production Server™. This model includes request methods, response codes, message headers, and message bodies. The RESTful API has the following characteristics:

The HTTP methods—POST, GET, and DELETE—form the primary mode of communication between client and server.
Unique Uniform Resource Identifiers (URIs) identify the resources that the server creates.
Message headers convey metadata such as the Content-Type of a request.
- The API supports application/json as the HTTP Content-Type header.
- The RESTful API for MATLAB function execution also supports application/x-google-protobuf as the HTTP Content-Type through the Java^®and .NET client APIs only.
The message body of the request contains information to be sent to the server.
- If you use JSON as the data serialization format, inputs to the MATLAB function contained within a deployed archive are represented in JSON and encapsulated within the body of a message.
- If you use protocol buffers (protobuf) for data serialization, the Java and .NET client libraries provide helper classes to internally create protobuf messages based on a proto format and returns the corresponding byte array. Use this byte array in the message body of the request.
The message body of the response contains information about a request such as state or results.
If you use protobuf for data serialization, the Java and .NET client libraries provide methods and classes to deserialize the protobuf responses.
The API supports both the synchronous and asynchronous modes of the server.

Note

The examples and graphics that follow use JSON as the data serialization format.

RESTful API for MATLAB Function Execution

Type	Purpose
Synchronous Execution (MATLAB Production Server)	Make synchronous requests to the server
Asynchronous Execution (MATLAB Production Server)	Make asynchronous requests to the server

RESTful API for Server Discovery and Diagnostics

Type	Purpose
Discovery Service (MATLAB Production Server)	Discover MATLAB functions deployed on the server
Health Check (MATLAB Production Server)	Check server health

Synchronous Execution

In synchronous mode, after a client posts a request, the server blocks all further requests until it has completed processing the original request. After processing is complete, the server automatically returns a response to the client.

RESTful API Calls for Synchronous Mode

Call	Purpose
POST Synchronous Request (MATLAB Production Server)	Make a synchronous request to the server, and wait for a response

The following graphic illustrates how the RESTful API works in synchronous mode.

When the server receives a request in synchronous mode, it blocks all other requests till it finishes processing the current request.

Example: Synchronous Execution of Magic Square Using RESTful API and JSON

This example shows how to use the RESTful API and JSON by providing two separate implementations—one using JavaScript^® and the other using Python^® . When you execute this example, the server returns a list of 25 comma-separated values. These values are the output of the deployed MATLAB function mymagic, represented in column-major format. The MATLAB code for the mymagic function follows.

function out = mymagic(in)
out = magic(in);

For this example to run, a MATLAB Production Server instance containing the deployed MATLAB function mymagic needs to be running. For more information on how to create a deployable archive, see Create a Deployable Archive for MATLAB Production Server. For more information on setting up a server, see Create a Server (MATLAB Production Server).

JavaScript Implementation

With the JavaScript implementation of the RESTful API, you include the script within the <script> </script> tags of an HTML page. When you open this HTML page in a web browser, the server returns the values of the mymagic function. Note that the server needs to have CORS enabled for JavaScript code to work. For more information on how to enable CORS, see cors-allowed-origins (MATLAB Production Server).

Code:

restApiSyncMagicJavaScript.html

Python Implementation

This example uses Python 2.x. If you are using Python 3.x, you must change some portions of the code.

Code:

restApiSyncMagicPython.py

To learn how to deploy a MATLAB function on MATLAB Production Server and invoke it using RESTful API and JSON, see Web-Based Tool Using RESTful API, JSON, and JavaScript.

Asynchronous Execution

In asynchronous mode, a client is able to post multiple requests, and in each case the server responds by creating a new resource and returning a unique URI corresponding to each request. The URI is encapsulated within the body of the response message. The client can use the URI returned by the server for the purposes of querying and retrieving results among other uses.

RESTful API Calls for Asynchronous Mode

Call	Purpose
POST Asynchronous Request (MATLAB Production Server)	Make an asynchronous request to the server
GET Representation of Asynchronous Request (MATLAB Production Server)	View how an asynchronous request made to the server is represented
GET Collection of Requests (MATLAB Production Server)	View a collection of requests
GET State Information (MATLAB Production Server)	Get state information of a request
GET Result of Request (MATLAB Production Server)	Retrieve the results of a request
POST Cancel Request (MATLAB Production Server)	Cancel a request
DELETE Request (MATLAB Production Server)	Delete a request

The following graphic illustrates how the RESTful API works in asynchronous mode. The graphic does not cover all the RESTful API calls. For a complete list of calls, see the preceding table.

Asynchronous request processing.

Example: Asynchronous Execution of Magic Square Using RESTful API and JSON

This example shows how to use the RESTful API and JSON for asynchronous execution using JavaScript. When you execute this example, the server returns a list of 100 comma-separated values. These values are the output of the deployed MATLAB function mymagic, represented in column-major format. The MATLAB code for the mymagic function follows.

function out = mymagic(in)
out = magic(in);

Code:

restApiAsyncMagicJavaScript.html

<!DOCTYPE html>
<html>

    <head>
        <title>Magic Square</title>
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
        <script>
            // MPS RESTful API (Asynchronous): Specify URL
            var hostname = "http://localhost:9910";
            var mode = "async";
            var clientID = "client100";
            var ctfName = "mymagic";
            var matlabFuncName = "mymagic"
            var url = hostname + "/" + ctfName + "/" + matlabFuncName + "?mode=" + mode + "&client=" + clientID;
            // Specify arguments
            var params = {
                "nargout": 1,
                "rhs": [100],
                "outputFormat": {"mode": "small"}
            };
            $.ajax(url, {
                data: JSON.stringify(params),
                //MPS RESTful API (Asynchronous): Specify Content-Type to application/json and Specify HTTP POST method
                contentType: 'application/json',
                method: 'POST',
                dataType: 'json',
                success: function(response) {
                    // Print Request URI to webpage
                    $("#requestURI").html('<strong>Request URI: </strong>' + hostname + response.self);
                    pollUsingUp(response);
                }
            });
            // Polling Server using UP
            function pollUsingUp(request) {
                setTimeout(function() {
                    var newSeq = parseInt(request.lastModifiedSeq) + 1;
                    var queryURI = hostname + request.up + "?since=" + newSeq + "&ids=" + request.id;
                    $.ajax({
                        url: queryURI,
                        method: 'GET',
                        dataType: 'json',
                        success: function(response) {
                            //Poll again if no data about the request was received.
                            if (response.data.length == 0) {
                                pollUsingUp(request);
                                return;
                            }

                            var requestResource = response.data[0];
                            // Print "state" of request
                            $("#state").html('<strong>State: </strong>' + requestResource.state);


                            if (requestResource.state != "READY" && requestResource.state != "ERROR") {
                                //Keep polling if the request is not done yet.
                                pollUsingUp(requestResource);
                            } else {
                                var requestURI = hostname + requestResource.self;
                                var responseURI = hostname + requestResource.self + "/result";
                                // Get result.
                                $.ajax({
                                    url: responseURI,
                                    // MPS RESTful API (Asynchronous): Specify HTTP GET method
                                    method: 'GET',
                                    dataType: 'json',
                                    success: function(response) {
                                        if (response.hasOwnProperty("lhs")) {
                                            $("#demo").html('<p>' +
                                                response.lhs[0] + '</p>');
                                            //Uncomment the next line if using JSON large representation
                                            //response.lhs[0].mwdata + '</p>');

                                        } else if (response.hasOwnProperty("error")) {
                                            alert("Error: " + response.error.message);
                                        }
                                        // MPS RESTful API (Asynchronous): Specify HTTP DELETE method
                                        $.ajax({
                                            url: requestURI,
                                            method: 'DELETE'
                                        });
                                    }
                                });
                            }
                        }
                    });
                }, 200);
            }
        </script>
    </head>

    <body>
        <p><strong>MPS RESTful API and JSON EXAMPLE</strong></p>
        <p> >> mymagic(5)</p>
        <p id="requestURI"></p>
        <p id="state"></p>
        <p id="demo"></p>
        <p> # output from server returned in column-major format </p>
    </body>

</html>

Asynchronous Request Execution on Azure Using HTTPS

A MATLAB Production Server deployment on Azure^® provides an HTTPS endpoint URL to invoke MATLAB functions deployed to the server. The Azure application gateway provides the HTTPS endpoint URL.

The Azure application gateway provides cookie-based session affinity, where it uses cookies to keep a user session on the same server. On receiving a request from a client program, the application gateway sets the Set-Cookie HTTP response header with information about the server virtual machine (VM) that processes the request. A client program that uses asynchronous requests to execute a MATLAB function deployed to the server must set the Cookie HTTP request header with the value of the Set-Cookie header for all subsequent requests. This ensures that same server VM that processes the first request processes all subsequent requests for that session.

For more information about the architecture and resources for MATLAB Production Server on Azure, see Architecture and Resources on Azure (MATLAB Production Server) and Architecture and Resources on Azure (MATLAB Production Server).

Discovery Service

Use the discovery service to learn about the MATLAB functions that you deploy to the server. The discovery service returns information about the deployed MATLAB functions as a JSON object. The object is a multilevel nested structure and at a high level displays the discovery schema version and a list of deployed archives. Each archive contains information about the deployed MATLAB functions and their function signatures. For more information about the JSON object, see JSON Response Object.

To use the discovery service, you must enable the discovery service on the server by setting the --enable-discovery property in the main_config server configuration file.

To get useful information when using the discovery service, you must include a JSON file containing function signatures of the MATLAB functions that you want to deploy when creating the deployable archive. For information on how to create a deployable archive, see Create a Deployable Archive for MATLAB Production Server. For information about creating the JSON file containing function signatures, see MATLAB Function Signatures in JSON.

Call the discovery service using the HTTP GET method.

RESTful API Calls for Discovery Service

Call	Purpose
GET Discovery Information	Discover MATLAB functions deployed on the server

The response from the server is a JSON object.

Example of a response to the GET discovery information request.

JSON Response Object

Object {;}

Name	Description
`discoverySchemaVersion`	Version number for the discovery schema. Example value:`1.0.0`
► `archives`	List of deployed archives. See Archives.

Name	Description
`archiveSchemaVersion`	Version number of the archive schema. Example value: `1.1.0`
`archiveUuid`	Unique identifier.
`name`	Name of the CTF archive.
`matlabRuntimeVersion`	MATLAB Runtime version. Example value: `9.5.0`
`typedefs`	If you deploy MATLAB functions that require cell arrays or structs as inputs, you must define them as `typedefs`. For details, see Typedefs.
`► functions`	A function object for each function that you deploy. For details, see Functions.

Typedefs

typedefs

Functions

functions

Health Check

Use the health check API to determine if the server has a valid license and is able to process HTTP requests. The health check classifies the server as healthy or unhealthy depending on whether the server has a valid license and can communicate with the network license manager. For more information on licensing, see Manage Licenses for MATLAB Production Server (MATLAB Production Server).

Server Health	HTTP Response Status Code	Description
Healthy	200 OK	A server is healthy when it is in one of the following states: The server is operating with a valid license. The server is communicating with the network license manager, and the required number of license keys are checked out. The server has lost communication with the network license manager, but the server is still fully operational and will remain operational until the end of the grace period as specified by the `license-grace-period` (MATLAB Production Server) property.
Unhealthy	503 Health Check Failed	The server has lost communication with the network license manager for a period of time exceeding the grace period. Request processing has been suspended, but the server is actively attempting to reestablish communication with the network license manager. Request processing resumes if the sever is able to reestablish communication with the License Manager.

If the health check is successful, the response from the server is a JSON object indicating that the server is healthy.

{
  "status": "ok"
}

A failed health check indicates that the server is unavailable to process HTTP requests but does not provide additional information about the cause of failure in the response body. Server administrators can use mps-status (MATLAB Production Server) to get detailed information about the server status. You must be on the same system as the server to run mps-status.

RESTful API Call for Health Check

Call	Purpose
GET Server Health (MATLAB Production Server)	Get information about the overall health of the server

Documentation

RESTful API

Synchronous Execution

Example: Synchronous Execution of Magic Square Using RESTful API and JSON

JavaScript Implementation

Python Implementation

Asynchronous Execution

Example: Asynchronous Execution of Magic Square Using RESTful API and JSON

Asynchronous Request Execution on Azure Using HTTPS

Discovery Service

JSON Response Object

Archives

Typedefs

Functions

Health Check

See Also

Related Topics

MATLAB Compiler SDK Documentation

Support