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® client API 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 client library provides 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 client library provides 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

TypePurpose

Synchronous Execution

Make synchronous requests to the server

Asynchronous Execution

Make asynchronous requests to the server

RESTful API for Server Discovery and Diagnostics

TypePurpose

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

CallPurpose
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 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.

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 Bond Pricing Tool Using 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

CallPurpose
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);

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.

Code:

 restApiAsyncMagicJavaScript.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 and Architecture and Resources on Azure.

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

CallPurpose
GET Discovery Information

Discover MATLAB functions deployed on the server

The response from the server is a JSON object.

JSON Response Object

 Object {;}

Archives

 archives

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 HealthHTTP Response Status CodeDescription
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

CallPurpose
GET Server HealthGet information about the overall health of the server

See Also

Related Topics