Main Content

Create MATLAB REST Function Services

You can create MATLAB® REST function services that allow client applications to call user-defined MATLAB functions over the HTTPS protocol. The service enables communication between your programs and MATLAB regardless of your platform and execution environment. You can call your own authored MATLAB functions using any programming language or application that can make a REST call, either locally or remotely.

Note

Only you can execute functions on your MATLAB.

REST function services are available for desktop MATLAB only. The service is not supported for deployed applications, MATLAB Production Server™ workers, MATLAB Online™, MATLAB Parallel Server™, and MATLAB Web App Server™.

Create Service to Local Functions

This example shows how to create a RESTFunctionService object named MyService to provide local clients access to your MATLAB functions myAdd, myMagic, and mySub.

service = restFunctionService("MyService",["myAdd" "myMagic" "mySub"])
service = 
  RESTFunctionService with properties:

                 Name: "MyService"
            Functions: ["myAdd"    "mySub"]
     ClientAccessMode: local
    FunctionConnector: [1×1 matlab.engine.rest.RESTFunctionConnector]
    ClientRequestInfo: [0×0 matlab.engine.rest.ClientRequestInfo]
               Status: notrunning

Start the service.

info = start(service)
info = 
  ClientRequestInfo with properties:

           ClientAccessMode: local
                 RequestUrl: "https://localhost:9920/matlab/feval/v1/MyService"
        CertificateLocation: "C:\Users\<username>\AppData\Roaming\MathWorks\restfcnconnector\publickey.pem"
    RESTPersonalAccessToken: "VAAKeo/2MaCzb72rMv1TX0df/HbjSSL47kWy5B694BE="

For information about using the data in the ClientRequestInfo object info in your client application to create a request using the POST method, see Call User-Defined Function with MATLAB REST Function Services.

Display the properties of the RESTFunctionConnector object which manages the communication between MATLAB and your client application:

service.FunctionConnector
ans = 
  RESTFunctionConnector with properties:

                         Port: 9920
                  LogLocation: "C:\Users\<username>\AppData\Roaming\MathWorks\restfcnconnector\logs"
                     HostName: "localhost"
             ClientAccessMode: local
                 ServiceNames: "MyService"
      RESTPersonalAccessToken: "VAAKeo/2MaCzb72rMv1TX0df/HbjSSL47kWy5B694BE="
          TokenExpirationDate: 22-Feb-2024
                  Certificate: "C:\Users\<username>\AppData\Roaming\MathWorks\restfcnconnector\publickey.pem"
    CertificateExpirationDate: 22-Jan-2025
                      BaseURL: "https://localhost:9920/matlab/feval/v1"
                       Status: running

Function Lists

When you configure a REST function service, you specify the functions that make up the service available to external applications. Your function must follow these guidelines:

  • User-defined function — You cannot call MATLAB functions directly. Instead, you must wrap them in your own function.

  • Function behavior — When you use a RESTful API, you make requests over the internet. A REST function service does not detect unsafe behavior inside your function.

  • Supported function arguments — Your function must use supported data types for input and output arguments. For more information, see JSON Representation of MATLAB Data Types.

  • One function per request — The function name is part of the request URL.

Tokens

A REST function service generates user tokens that are stored in memory. You can display the token using the RESTPersonalAccessToken property of ClientRequestInfo objects, as shown in the example Create Service to Local Functions.

  • MATLAB assigns a unique token to each user on each machine.

  • The token does not contain user identity information.

  • You must not share tokens with other users in keeping with your license agreement. Protecting the token is important to ensure that only you are able to execute functions on your MATLAB and not other users with access to your machine.

  • You can specify the lifetime of the token. The default is 30 days. You can specify a lifetime of up to one year. To specify the lifetime, call the changeToken function on a RESTFunctionConnector object.

  • You can revoke a token and generate a new one using the changeToken function.

HTTPS and Certificates

A client application communicates with MATLAB using HTTPS which is an encrypted text communication protocol. Certificates allow both the client and the server to encrypt and decrypt the text sent between them.

Your application must support HTTPS requests with a self-signed certificate issued by MATLAB or with an external certificate you create. MATLAB generates self-signed certificates which are valid for 365 days. If the certificate has expired, or you want to use your own certificate or generate a new certificate, call the changeCertificate function on a RESTFunctionConnector object.

Private keys are stored persistently on the machine but are not accessible to MATLAB.

MathWorks Service Host Updates

Since R2024b

MATLAB REST function services rely on the MathWorks® Service Host (MSH) for communication with MATLAB from client applications. MSH regularly releases updates and restarts automatically after updates are installed. If services are running before the update, the REST function connector stops during the update and then automatically restarts, along with the running services, when the MSH is available.

Any computations or requests made by your program during the update cannot be recovered. If you have long-running function calls, you can specify a preferred restart time to avoid interruption of your workflow and possible loss of data. For more information, see the PreferredRestartHour property.

Remote Function Calls and Security Implications

By default, only local clients can access a REST function service. To allow remote access, get a RESTFunctionConnector object and set the ClientAccessMode property to remote. The service displays a warning about the risks of allowing remote access. You must confirm your understanding before allowing remote access.

Note

Security Considerations: Allowing remote access makes it possible to control the machine remotely using MATLAB function calls. This accessibility may potentially expose your machine to security threats. Avoid remote access on public and untrusted networks. Consult with your IT administrator before allowing remote access to confirm that appropriate security measures are in place. You are responsible for the behavior of your functions.

Limitations

A REST function service does not support these features:

  • Hypertext transfer protocol (HTTP) — The service supports HTTPS.

  • Asynchronous requests — The service supports synchronous HTTPS POST requests only.

  • Calls to built-in MATLAB functions — The service supports user-defined MATLAB functions. For information about supported data types, see JSON Representation of MATLAB Data Types.

  • IPv6 addresses — The service supports IPv4 addresses.

See Also

Functions

Objects

Related Topics