RESTful API for Secure Management of Deployable Archives

The MATLAB® Production Server™ RESTful API for secure upload of deployable archives lets you securely upload, manage, and deploy archives to a server. You can use the API to:

  • Deploy archives to a server.

  • Check whether an archive is deployed to the server.

  • List all archives deployed to a server.

  • Update archives on the server.

  • Delete archives from the server.

All these services return responses in JSON format.

Characteristics of RESTful API

The RESTful API for secure management of deployable archives uses the HTTP request-response model for communication with MATLAB Production Server. This model includes request methods, response codes, message headers, and message bodies. The RESTful API for secure management of deployable archives has these characteristics:

  • The HTTP methods POST, GET, PUT and DELETE form the primary mode of communication between client and server.

  • Requests to the server that use the GET and DELETE method do not have a message body, so you do not have to set the Content-Type header in the request.

  • The message body of the response contains information specific to a request such as information about archives deployed to the server.

  • Unique uniform resource identifiers (URIs) identify the resources that the server creates.

Enable RESTful API for Secure Management of Deployable Archives

To enable the RESTful API for secure management of deployable archives, uncomment these entries in the main_config file:

  • --enable-archive-management — This entry enables the API

  • --request-size-limit — This entry sets the maximum request body size and has a default setting of 64MB, with a maximum allowed value of 1GB. The API does not support chunked transfer encoding for uploading deployable archives.

Configure Security for Deployable Archives

Access control is optional and not enabled by default. It is intended to limit access for uploading and executing deployable archives in open-access systems, since doing so poses a security risk. You can enable it by uncommenting the following entries in the main_config file:

  • --access-control-provider OAuth2

  • --access-control-config ./config/jwt_idp.json

  • --access-control-policy ./config/ac_policy.json

For more information on access control, see Application Access Control. When access control is enabled, uploading, updating and deleting archives require the "modify" action in the access control policy file, while listing archives does not.

Upload Deployable Archives

You can use the deployable archive upload service to upload a deployable archive to MATLAB Production Server using an HTTP request. For more information on creating deployable archives for MATLAB Production Server, see Create Deployable Archive for MATLAB Production Server. To upload your archive, use this request format.

POST /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Content-Type: application/octet-stream
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

  • filename — The name of the deployable archive without the .ctf file extension. The API only accepts 1 filename query parameter with 1 value at a time.

  • JSON Web Token — Authorization token

  • content-length — Content length in bytes

  • hostname — Host name for the server instance

  • port — Port name for the server instance

After your archive is uploaded, MATLAB Production Server returns a JSON object with a body of the following form:

{
  "action": "Upload",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

If you upload a file that is not a valid deployable archive, the file will appear in the auto_deploy directory. However, it will not execute.

To upload a deployable archive using a POST request, the request must use the name of an archive that does not already exist on the server. If you attempt to upload a deployable archive that already exists on the server, MATLAB Production Server returns an error. To update an existing deployable archive, see Update Deployable Archives.

MATLAB Example with Authorization Token

You can use the following MATLAB function to upload a deployable archive if you have security configured. The function takes a deployable archive with extension .ctf, a host name, a port number, and a JSON web token. The function then displays the JSON object returned by MATLAB Production Server and uses the matlab.net.http.RequestMessage (MATLAB) class to format the HTTP request message and send it to the server.

function upload_authz(ctf, host, port, token)
    % ctf: Name of archive without .ctf extension, specified as string
    % host: host name, specified as string
    % port: port number, specified as int
    % token: JSON Web Token, specified as string

    [~,ctfName,~] = fileparts(ctf);
    url = sprintf("http://%s:%d/api/archives?ctf=%s",host,port,ctfName);

    % List
    list_response = webread(url);
    disp(list_response.archive);
    fp = fopen(ctf);
    closeFP = onCleanup(@()fclose(fp));
    data = fread(fp,'*uint8');

    % Create the Content-Type and Authorization HTTP Header fields:
    contentTypeField = matlab.net.http.field.ContentTypeField('application/octet-stream');
    authzField = matlab.net.http.field.AuthorizationField('Authorization',['Bearer ',token]);

    % Create the request type
    requestMethod = matlab.net.http.RequestMethod.POST;
    alreadyThere = ismember(ctfName, list_response.archive) && list_response.result;
    if (alreadyThere) % update if already exists
        requestMethod = matlab.net.http.RequestMethod.PUT;
    end
    % Create the request message with POST method and binary data
    request = matlab.net.http.RequestMessage(requestMethod, ...
        [contentTypeField,authzField],data);

    % Create the URI with query parameters:
    mpsURI = matlab.net.URI(url);
    params = struct('ctf',ctfName);
    mpsURI.Query = params;

    % Send upload request
    upload_response = request.send(mpsURI);
    disp(upload_response);
    upload_result = upload_response.Body.Data;
    disp(upload_result);
end

MATLAB Example Without Authorization Token

If you do not have security configured, you can use the following MATLAB function to upload a deployable archive. The function takes a deployable archive with extension .ctf, a host name and a port number. The function then displays the JSON object returned by MATLAB Production Server and uses the matlab.net.http.RequestMessage (MATLAB) class to format the HTTP request message and send it to the server.

function upload(ctf, host, port)
    % ctf: Name of archive without .ctf extension, specified as string
    % host: host name, specified as string
    % port: port number, specified as int

    [~,ctfName,~] = fileparts(ctf);
    url = sprintf("http://%s:%d/api/archives?ctf=%s",host,port,ctfName);

    % List
    list_response = webread(url);
    disp(list_response.archive);
    fp = fopen(ctf);
    closeFP = onCleanup(@()fclose(fp));
    data = fread(fp,'*uint8');

    % Create the Content-Type and Authorization HTTP Header fields:
    contentTypeField = matlab.net.http.field.ContentTypeField('application/octet-stream');

    % Create the request type
    requestMethod = matlab.net.http.RequestMethod.POST;
    alreadyThere = ismember(ctfName, list_response.archive) && list_response.result;
    if (alreadyThere) % update if already exists
        requestMethod = matlab.net.http.RequestMethod.PUT;
    end
    % Create the request message with POST method and binary data
    request = matlab.net.http.RequestMessage(requestMethod, ...
        contentTypeField,data);

    % Create the URI with query parameters:
    mpsURI = matlab.net.URI(url);
    params = struct('ctf',ctfName);
    mpsURI.Query = params;

    % Send upload request
    upload_response = request.send(mpsURI);
    disp(upload_response);
    upload_result = upload_response.Body.Data;
    disp(upload_result);
end

cURL Example

curl -v -X POST  -H "Content-Type: application/octet-stream" -H "Authorization: Bearer <JSON Web Token>" \
--data-binary @<filename>.ctf http://<hostname>:<port>/api/archives?ctf=<filename>

In this cURL example, the --data-binary @<filename>.ctf name option defines the file name of the deployable archive to upload, while the URL query parameter defines the name of the archive used on the server and can potentially be different.

List Deployable Archives

You can use the deployable archive list service to check whether a specific deployable archive is deployed to an instance of MATLAB Production Server or to list all deployed archives on an instance of MATLAB Production Server.

Search for a specific archive:

GET /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

List all archives on the server:

GET /api/archives HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

  • filename(optional) — The name of the deployable archive without the .ctf file extension. The API only accepts 1 filename query parameter with 1 value at a time.

  • JSON Web Token — Authorization token

  • content-length — Content length in bytes

  • hostname — Host name for the server instance

  • port — Port name for the server instance

If you include the ctf query parameter and populate it with the name of a deployable archive, the JSON response includes a result field that specifies whether the archive is deployed. The response body has the following form:

{
  "action": "List",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

If you do not include the ctf query parameter, then the service lists all archives deployed to the server. In this case, the response body includes a list of all archives deployed to the server:

{
  "version": "1.0.0",
  "archives": [
    {
      "archive": "filename1"
    },
    {
      "archive": "filename2"
    },
    {
      "archive": "filename3"
    }
  ]
}

cURL Example

List all archives on the server:

curl <hostname>:<port>/api/archives

Search for a specific archive:

curl <hostname>:<port>/api/archives?ctf=<filename>

Update Deployable Archives

You can use the update deployable archives service to update a deployable archive on an instance of MATLAB Production Server. The endpoint requires the filename of the deployable archive you want to update and an authorization token.

PUT /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Content-Type: application/octet-stream
Authorization: Bearer <JSON Web Token>
Content-Length: <content-length>

  • filename — The name of the deployable archive without the .ctf file extension. The API only accepts 1 filename query parameter with 1 value at a time.

  • JSON Web Token — Authorization token

  • content-length — Content length in bytes

  • hostname — Host name for the server instance

  • port — Port name for the server instance

The deployable archive update service returns a JSON object that confirms the name of the file that has been updated. The response body has the following form:

{
  "action": "Update",
  "archive": <filename>,
  "result": true
  "size": Size in bytes (if known)
}

To update a deployable archive using a PUT request, the request must use the name of an archive that already exists on the server. If you attempt to update a deployable archive that does not already exist on the server, MATLAB Production Server returns an error. To upload a new deployable archive, see Upload Deployable Archives.

cURL Example

curl -v -X PUT  -H "Content-Type: application/octet-stream" -H "Authorization: Bearer <JSON Web Token>" \
--data-binary @<filename>.ctf http://<hostname>:<port>/api/archives?ctf=<filename>

Delete Deployable Archives

You can use the deployable archive delete service to remove a deployable archive from a server instance. The endpoint requires the filename of the deployable archive you want to delete and an authorization token.

DELETE /api/archives?ctf=<filename> HTTP/1.1
Host: <hostname>:<port>
User-Agent: curl/7.88.1
Accept: */*
Authorization: Bearer <JSON Web Token>

  • filename — The name of the deployable archive without the .ctf file extension. The API only accepts 1 filename query parameter with 1 value at a time

  • JSON Web Token — Authorization token

  • hostname — Host name for the server instance

  • port — Port name for the server instance

The deployable archive delete service returns a JSON object that confirms the name of the file that has been deleted. If the archive does not exist, it produces a 403 error instead. The response body has the following form:

{
  "action": "Delete",
  "archive": <filename>,
  "result": true
}

cURL Example

% curl -v -X DELETE -H "Authorization: Bearer <JSON Web Token>" \
 http://<hostname>:<port>/api/archives?ctf=<filename>

See Also

| | (MATLAB Compiler SDK) | (MATLAB Compiler SDK)

Topics