RESTful API

Synchronous Execution
Example: Synchronous Execution of Magic Square using RESTful API and JSON
Asynchronous Execution
Example: Asynchronous Execution of Magic Square using RESTful API and JSON

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.
Support for both the synchronous and asynchronous modes of the server.

Synchronous Execution

In synchronous mode, once a client posts a request, the server blocks all further requests until it has completed processing the original request. Once 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 twenty-five 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 examples 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 one-hundred 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>

Was this topic helpful?

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

MATLAB Production Server Documentation

Other Documentation

Support