Main Content

HTTP Data Type Conversion

The MATLAB® HTTP interface automatically converts data types used in HTTP messages to and from MATLAB types.

Converting Data in Request Messages

When sending a message with a payload, assign your MATLAB data to the Data property in a MessageBody object, then send it as a Body property in a RequestMessage object. The type of your MATLAB data depends on the HTTP Content-Type of the message. If you do not specify a Content-Type, then MATLAB assumes Content-Type values, as described in Content-Type Not Specified.

This table shows how MATLAB converts Data to a payload in a request message based on the type/subtype properties and the charset attribute that you specify in the Content-Type header field. The asterisk character (*) means any subtype.

Content-Type

MATLAB Type in MessageBody.Data Property

application/json

Data converted to a Unicode® value using the jsonencode function. MATLAB then uses the unicode2native function to convert the value to uint8, based on the charset attribute in the Content-Type header field.

If you already have JSON-encoded text, then assign the text to the Payload property instead of the Data property. MATLAB converts the value to uint8 using the charset attribute.

If the charset attribute is not specified, then the default charset value is UTF-8.

text/* for any subtype other than csv or xml

If Data is a character or string array or a cell array of character vectors, MATLAB reshapes and concatenates the text by row to form a vector.

If Data is any other type, MATLAB converts Data using the string function. The resulting string is converted to uint8 based on the charset.

If you did not specify a charset, the default depends on the subtype. For the following subtypes, the default is UTF-8:

  • json

  • jtml

  • javascript

  • css

  • calendar

For all other subtypes, MATLAB determines the charset. If all characters are in the ASCII range, then the charset is US-ASCII. Otherwise, the charset is UTF-8.

Note

Servers might not properly interpret text types encoded as UTF-8 without an explicit UTF-8 charset. For best results, explicitly specify UTF-8 if your data contains non-ASCII characters.

image/*

Data must be image data in a form acceptable to the imwrite function. Conversion of Data to uint8 depends on the subtype. For information about supported types and for controlling the conversion, see Supported Image Data Subtypes.

To control the conversion of your image data or to override the type of conversion based on the subtype, specify additional arguments to imwrite using a cell array. If you specify an image format argument (fmt), then it overrides the default conversion.

For example, the following code converts imageData to JPEG with compression quality 50 and sends the data to the specified url with Content-Type set to "image/jpeg".

body = MessageBody({imageData,'jpg','Quality',50});
req = RequestMessage('put',ContentTypeField('image/jpeg'),body);
resp = req.send(url);

  • application/xml

  • text/xml

If Data is an XML DOM in the form of a Java® org.w3c.dom.Document object, MATLAB converts it using the xmlwrite function.

If Data is a string or character vector, MATLAB converts it to uint8 using the specified charset. If not specified, the default charset value is UTF-8.

application/x-www-form-urlencoded

If Data is a vector of matlab.net.QueryParameter objects, then MATLAB converts it to a URL-encoded string. If it is a string or character vector, it is left unchanged.

audio/*

Data must be audio data in a form acceptable to the audiowrite function. Create a cell array containing an m-by-n matrix of audio data and a sampling rate in Hz. You can specify additional arguments to audiowrite by adding name-value pair arguments to the cell array.

MATLAB supports the following audio types:

  • audio/x-wav

  • audio/wav

  • audio/mp4

  • audio/vnd.wav

  • application/ogg

  • audio/flac

  • application/csv

  • text/csv

  • application/vnd.openxmlformats-
    officedocument.spreadsheetml.sheet

  • application/vnd.ms-excel

Data must be a table in a form suitable for the writetable function.

For csv subtypes, MATLAB converts Data to comma-delimited text using the specified charset. The default charset is US-ASCII.

For the other types, MATLAB converts Data to Excel® spreadsheet data.

To specify additional name-value pair arguments to writetable, create a cell array containing Data and the additional arguments. If you specify a 'FileType' argument, that type must be consistent with the subtype you specify.

Content-Type Not Specified

If you do not specify a Content-Type field in the request message, MATLAB assigns the type, subtype, and charset based on the type of the Data property. This assumed behavior might not result in the Content-Type you intended, or might fail to determine the type, so for best results, specify the Content-Type. The following table describes the assumed Content-Type based on Data. Types not listed might be handled, but the behavior for unlisted types is not guaranteed to remain the same in future releases.

MessageBody.Data Property Type
Content-Type Not Specified

Resulting Content-Type

string
character array
cell array of character vectors

text/plain

table

text/csv

cell vector whose first element is a table

text/csv — If FileType is csv, then there is a name,value pair in the vector with the value 'FileType','csv' or there is no such pair.

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet — If FileType is spreadsheet.

org.w3c.dom.Documentapplication/xml
uint8 vector

To send a uint8 vector without conversion and ignoring the Content-Type header field, set the Payload property instead of Data.

To send character-based data with no conversion, use the unicode2native function. This function uses the charset attribute to convert Data to a uint8 vector.

If the type is not one of those listed in the table, then MATLAB determines whether it is one of the following character-based types:

  • text/*

  • any type with a charset

  • application/*javascript

  • application/vnd.wolfram.mathematica.package

MATLAB converts these types to a string, using the charset, if specified, or US-ASCII for text/plain, UTF-8 for the application types, and the default MATLAB encoding for the other types.

Converting Data in Response Messages

When receiving a message with a payload, MATLAB converts the incoming byte stream (MessageBody.Data property) to an appropriate MATLAB type.

The following table is a list of the Content-Types that MATLAB recognizes in a response message, based the type/subtype properties and the charset attribute in the received Content-Type field. MATLAB converts the data only if the HTTPOptions.ConvertResponse property is true, which is the default. In the table, the asterisk character (*) means any characters.

Response Message Content-TypeMATLAB Type in MessageBody.Data Property
application/json

Data is converted to a string based on the charset and then to MATLAB data using the jsondecode function.

image/*

Data is converted to an image using the imread function with the specified subtype as the format, using default arguments. If imread returns more than one value, then Data is a cell array.

For the supported types of image data, see Supported Image Data Subtypes. If the subtype is not in this list, then the subtype is passed to imwrite as the format, which might or might not be supported.

audio/*

Data is converted using the audioread function to a cell array of two values, an m-by-n matrix of audio data and a sampling rate in Hz. The subtype determines the format used by audioread. The supported types are:

  • audio/wav

  • audio/x-wav

  • audio/vnd.wav

  • audio/mp4

  • audio/flac

application/ogg is not converted because ogg data does not necessarily contain audio only.

text/csv
text/comma-separated-values
application/csv
application/comma-separated-values

Data is converted to a table using readtable, with assumed 'FileType' of csv and charset, if specified, or the MATLAB default encoding.

application/*spreadsheet*

Data is converted to a table using readtable, with 'FileType' assumed to be 'spreadsheet'.

text/xml
application/xml

If Java is available, Data is converted to a Java org.w3c.dom.Document using the xmlread function.

If Java is not available, Data is processed as text/plain with the UTF-8 charset.

If the type is not one of those listed in the table, then MATLAB determines whether it is one of the following character-based types:

  • text/*

  • any type with a charset

  • application/*javascript

  • application/vnd.wolfram.mathematica.package

MATLAB converts these types to a string, using the charset, if specified, or US-ASCII for text/plain, UTF-8 for the application types, and the default MATLAB encoding for the other types.

If MATLAB does not support the type, or if the HTTPOptions.ConvertResponse property is set to false, then:

  • If the type is character-based, then Data contains the payload converted to string.

  • Otherwise, Data contains the raw uint8 vector.

If conversion of incoming data is attempted but fails (for example, "image/jpeg" data is not valid JPEG data), then the History property in the HTTPException thrown by the RequestMessage.send method contains the ResponseMessage with the Payload property set to the uint8 payload and, if the type is character-based, then Data is set to the payload converted to a string.

Supported Image Data Subtypes

The following subtypes are supported by the imwrite function as the specified format. For example, the format argument for subtype bmp is 'bmp'. The imread function converts the data with the specified subtype as the format.

Subtype

Format Used by
imwrite and imread

bmp

'bmp'

gif

'gif'

jpeg

'jpeg'

jp2

'jp2'

jpx

'jpx'

png

'png'

tiff

'tiff'

x-hdf

'hdf'

x-portable-bitmap

'pbm'

x-pcx

'pcx'

x-portable-graymap

'pgm'

x-portable-anymap

'pnm'

x-portable-pixmap

'ppm'

x-cmu-raster

'ras'

x-xwd

'xwd'

See Also

| | | | | | | | | | | | |