POST Asynchronous Request

Make an asynchronous request to the server

Description

Use a POST method to make an asynchronous request to the server. During asynchronous execution, this step is usually the first in the process.

The following sections use JSON as the data serialization format. For an example that shows how to use protobuf as the data serialization format with the Java® client API and the .NET client API, see Asynchronous RESTful Requests Using Protocol Buffers in the Java Client and Asynchronous RESTful Requests Using Protocol Buffers in .NET Client.

Request

HTTP Method

POST

URI

http://host:port/deployedArchiveName/matlabFunctionName

Query Parameters

NameDescriptionValue-Type
mode

(Required). Specify mode of communication.

async

client

(Optional). Specify an ID or name for the client making the request.

{client-id-string}

Example:

?mode=async&client=Nor101

Content-Type

  • application/json

Body

NameDescriptionValue-Type
nargout

Number of outputs that the client application is requesting from the deployed MATLAB® function. Note that MATLAB functions, depending on their intended purpose, can be coded to return multiple outputs. You can use nargout to specify a subset of these potential outputs.

number
rhs

Input arguments to the deployed MATLAB function, specified as an array of comma-separated values.

[arg1,arg2,arg3,...]
outputFormat

Specify whether the MATLAB output in the response should be returned using large or small JSON notation, and whether NaN and Inf should be represented as a JSON string or object. If the mode is not specified or the returned MATLAB data type does not support JSON small notation, the response is represented using JSON large notation.

For more information on the JSON representation of MATLAB data types, see JSON Representation of MATLAB Data Types.

{ "mode" : "small | large", "nanInfFormat" : "string | object" }

Example:

Single Input Argument:

{
 "nargout": 1, 
 "rhs": [5],
 "outputFormat" : { "mode" : "small,"nanInfFormat": "object"}
}
Multiple Input Arguments and Multiple Outputs:
{
 "nargout": 2, 
 "rhs": [3, 4, 5 ...],
 "outputFormat" : { "mode" : large", "nanInfFormat" : "string" }
}

Response

Success

HTTP Status Code

201 Created

Body

NameDescriptionValue-Type
idID of a particular request.{id-string}
selfURI of particular request.{request-uri-string}
upURI of a collection of requests tied to a particular client.{request-collection-uri-string}
lastModifiedSeqNumber indicating when a request represented by self was last modified.{server-state-number}
stateState of a request.{request-state-string}

List of states:

READING
IN_QUEUE
PROCESSING
READY
ERROR
CANCELLED

clientClient id/name that was specified as a query parameter while initiating a request.{client-id-string}

Example:

{
  "id": "a061c723-4724-42a0-b405-329cb8c373d6",
  "self": "/~e4a954fd-5eaf-4b54-aac2-20681b33d075/requests/a061c723-4724-42a0-b405-329cb8c373d6",
  "up": "/~e4a954fd-5eaf-4b54-aac2-20681b33d075/requests",
  "lastModifiedSeq": 6,
  "state": "READING",
  "client": ""
}

Error

HTTP Status Code

404 ResourceNotFound

405 MethodNotAllowed — No 'Access-Control-Allow-Origin' header. Enable CORS on server.

415 InvalidContentType

415 UnsupportedMediaType

Sample Call

HTTP

Request:

POST /mymagic/mymagic?mode=async HTTP/1.1
Host: localhost:9910 
Content-Type: application/json

{"rhs":[7],"nargout":1,"outputFormat":{"mode":"small","nanType":"string"}}

Response:

Status Code: 201 Created
Header: 
  Location: /~e4a954fd-5eaf-4b54-aac2-20681b33d075/requests/ad2363f3-26c1-4d48-88f8-6b7fb615f254
  X-MPS-Start-Time: 003472d705bd1cd2
  Content-Length: 248 
Body: 
{
  "id": "ad2363f3-26c1-4d48-88f8-6b7fb615f254",
  "self": "/~e4a954fd-5eaf-4b54-aac2-20681b33d075/requests/ad2363f3-26c1-4d48-88f8-6b7fb615f254",
  "up": "/~e4a954fd-5eaf-4b54-aac2-20681b33d075/requests",
  "lastModifiedSeq": 41,
  "state": "READING",
  "client": ""
}

JavaScript

var data = JSON.stringify(
    {   "rhs": [7],
        "nargout": 1,
        "outputFormat": {"mode": "small","nanType": "string"}
    }
);

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost:9910/mymagic/mymagic?mode=async");
xhr.setRequestHeader("content-type", "application/json");
xhr.addEventListener("readystatechange", function () {
    if (this.readyState === 4) {
        console.log(this.responseText);
    }
});
xhr.send(data);

Introduced in R2016b