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

TypePurpose

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

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

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

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

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

Related Topics