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.
Resources created by the server are uniquely identified using Uniform Resource Identifiers (URIs).
Metadata such as the content-type of a request is conveyed through a message header. The only supported content-type is application/json.
Inputs to the MATLAB function contained within a deployed archive are represented in JSON and encapsulated within the body of a message.
The message body of the response contains information about a request such as state or results.
It supports both the synchronous and asynchronous modes of the server.

API

Type	Purpose
Synchronous Execution	Make synchronous requests to the server
Asynchronous Execution	Make asynchronous requests to the server
Discovery Service	Discover MATLAB functions deployed on the server
Health Check	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`	Make a synchronous request to the server, and wait for a response

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

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.

JavaScript Implementation

With the JavaScript implementation of the RESTful API, you include the script within the <script> </script> tags of an HTML page. When this HTML page is opened in a web browser, the values of the mymagic function are returned. Note that the server needs to have CORS enabled for JavaScript code to work. For more information, see cors-allowed-origins.

Code:

restApiSyncMagicJavaScript.html

Python Implementation

This example uses Python 2.x. If you are using Python 3.x, you need to 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 Example: Web-Based Bond Pricing Tool Using JavaScript.

Asynchronous Execution

In asynchronous mode, a client can 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`	Make an asynchronous request to the server
`GET Representation of Asynchronous Request`	View how an asynchronous request made to the server is represented
`GET Collection of Requests`	View a collection of requests
`GET State Information`	Get state information of a request
`GET Result of Request`	Retrieve the results of a request
`POST Cancel Request`	Cancel a request
`DELETE Request`	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.

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>

Discovery Service

You can use the discovery service to learn about the MATLAB functions deployed to the server. The discovery service returns information about 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. Information about the deployed MATLAB functions and their function signatures is contained within each of the listed archives. For details, see JSON Response Object.

To use the discovery service, you need to enable the discovery service on the server. You can do this by uncommenting the option --enable-discovery in the server's main_config file.

To get useful information when using the discovery service, you need to include a JSON file containing function signatures of the deployed MATLAB functions when creating the deployable archive. For more information, 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.

You can 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.

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 your deployed MATLAB functions require cell arrays or structs as inputs, they need to be defined as `typedefs`. For details, see Typedefs
`► functions`	A function object for each deployed function. 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.

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` 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 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	Get information about the overall health of the server

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

Discovery Service

JSON Response Object

Archives

Typedefs

Functions

Health Check

See Also

Related Topics

MATLAB Production Server Documentation

Support

Try MATLAB, Simulink, and Other Products