weboptions

Specify parameters for RESTful web service

collapse all in page

Syntax

options = weboptions
options = weboptions(Name,Value)

Description

options = weboptions returns a default weboptions object to specify parameters for a request to a web service. A weboptions object can be an optional input argument to the webread, websave, and webwrite functions. For options not supported by the weboptions function, see the Call Web Services from MATLAB Using HTTP.

example

options = weboptions(Name,Value) specifies one or more properties of a weboptions object. To remove sensitive information from code, see loadenv.

example

Examples

Default weboptions Object

Create a default weboptions object and display the default values for its properties.

options = weboptions
options = 

  weboptions with properties:

      CharacterEncoding: 'auto'
              UserAgent: 'MATLAB 9.7.0.1112323 (R2019b)'
                Timeout: 5
               Username: ''
               Password: ''
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'auto'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'default'

User Name and Password in weboptions Object

Set your web service user name and password in a weboptions object. You can use the weboptions object as an input argument to webread, websave, or webwrite when your web service requires authentication. Keep your sensitive information encrypted by using secretID objects.

options = weboptions(Username=secretID("MathWorks.Username"), ...
                     Password=secretID("MathWorks.Password"))
options = 
  weboptions with properties:

      CharacterEncoding: 'auto'
              UserAgent: 'MATLAB 25.1.0.2966447 (R2025a) Update 1'
                Timeout: 5
               Username: MathWorks.Username (secretID)
               Password: MathWorks.Password (secretID)
                KeyName: ''
               KeyValue: ''
            ContentType: 'auto'
          ContentReader: []
              MediaType: 'auto'
          RequestMethod: 'auto'
            ArrayFormat: 'csv'
           HeaderFields: []
    CertificateFilename: 'default'

A secretID object only displays the identifier name.

options.Password
ans = 
  secretID with properties:

    Name: "MathWorks.Password"

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: weboptions('Timeout',60) creates a weboptions object that sets the timeout connection duration to 60 seconds.

The encoding used by webread to convert web content to characters, specified as a string scalar or character vector. Common encodings include 'US-ASCII', 'UTF-8', 'latin1', 'Shift_JIS', and'ISO-8859-1'. The default encoding depends on the content type. If you get garbled text, then the webread encoding might be different from the encoding used by the document. Try setting CharacterEncoding to UTF-8.

User agent identification, specified as a string scalar or character vector indicating the client user agent.

Time out connection duration in seconds, specified as a positive numeric scalar. The value is the number of seconds to wait to receive the initial response (header) from the server after sending the last packet of a request. Timeout is equivalent to the ResponseTimeout property in the matlab.net.http.HTTPOptions class. The maximum value is 2147.483647 seconds. Use Inf to set the maximum value.

Some operating systems have a maximum timeout enforced by the system. This timeout takes effect even if the value of Timeout is greater than the maximum. For example, on Windows® 10, this timeout is 21 seconds.

User identifier, specified as a string scalar or character vector for basic and/or digest HTTP authentication (no encryption). For information about Basic HTTP Authentication Scheme, see RFC 7617 on the RFC Editor website. For information about HTTP Digest Access Authentication, see RFC 7616.

User authentication password, specified as a string scalar or character vector for basic and/or digest HTTP authentication (no encryption). If you display a weboptions object with Password set, then the value is displayed as a character vector containing ‘*’. However, the object stores the value of Password as plain text.

Name of a key, specified as a string scalar or character vector. KeyName is an additional name to add to the HTTP request header. For example, KeyName can be a web service API key name.

Example: weboptions('KeyName','duration','KeyValue',7) creates a weboptions object that contains a key name, duration, defined by a web service.

Value of a key, specified as a string scalar, a character vector, or a numeric or logical value to add to the HTTP request header. KeyValue is the value of a key specified by KeyName.

Example: weboptions('KeyName','duration','KeyValue',7) creates a weboptions object that contains a key value, 7, paired with a key name, duration.

Names and values of header fields, specified as an m-by-2 array of strings or cell array of character vectors to add to the HTTP request header. HeaderFields{i,1} is the name of a field and HeaderFields{i,2} is its value.

These header fields add to or replace fields automatically added by webread, webwrite, or websave. Normally these fields are added, but if the name of one of these fields is a case-insensitive match to one of the fields that would be automatically added, and that field does not support multiple values (for example, Content-Type), then the value you specify is used instead. Some fields whose value is necessary to send a request successfully, such as Connection and Content-Length, cannot be overridden.

Example: weboptions('HeaderFields',{'Content-Length' '78';'Content-Type' 'application/json'}) creates a weboptions object that contains two header fields: Content-Length with value 78 and Content-Type with value application/json.

Example: options.HeaderFields = {'Expect',''} suppresses a header field (Expect) by specifying its value as an empty string. This might be required in cases where the server is not able to correctly handle the header field in a request.

Content type, specified as a string scalar or character vector. Use ContentType to request that the server preferentially return data in a particular format. webread uses this value to convert the response to a MATLAB® type. The server returns this content type if possible, but is not obligated to do so.

ContentType Value

Output Type

"auto" (default)

Output type is automatically determined based on the content type specified by the web service.

"text"

Character vector for content types:

  • text/plain

  • text/html

  • text/xml

  • application/xml

  • application/javascript

  • application/x-javascript

  • application/x-www-form-urlencoded

If a web service returns a MATLAB file with a .m extension, the function returns its content as a character vector.

For text content returned from a server, if no character encoding is specified by the server or by the user, then the function uses UTF-8 by default.

"image"

Numeric or logical matrix for image/format content.

For supported image formats, see Supported File Formats for Import and Export.

"audio"

Numeric matrix for audio/format content.

For supported audio formats, see Supported File Formats for Import and Export.

"binary"

uint8 column vector for binary content (that is, content not to be treated as type char).

"table"

Scalar table object for spreadsheet and CSV (text/csv) content.

Alternatively, to read table data from a website, call readtable with the filename argument specified as a URL. For an example, see Read HTML Webpage as Table.

"json"

char, numeric, logical, structure, or cell array for application/json content.

"xmldom"

Java® Document Object Model (DOM) node for text/xml or application/xml content. If ContentType is not specified, the function returns XML content as a character vector.

"raw"

char column vector for "text", "xmldom", and "json" content. The function returns any other content type as a uint8 column vector.

Example: weboptions('ContentType','text') creates a weboptions object that instructs webread to return text, JSON, or XML content as a character vector.

Content reader, specified as a function handle. You can create a weboptions object with ContentReader specified, and pass the object as an input argument to webread. Then webread downloads data from a web service and reads the data with the function specified by the function handle. webread ignores ContentType when ContentReader is specified.

Example: weboptions('ContentReader',@readtable) creates a weboptions object that instructs webread to use readtable to read content as a table.

Media type, specified as a string scalar, a character vector, or a matlab.net.http.MediaType object. MediaType specifies the type of data webwrite sends to the web service. It specifies the content type that MATLAB specifies to the server, and it controls how the webwrite data argument, if specified, is converted. For more information, see RFC 6838 Media Type Specifications and Registration Procedures on the RFC Editor website.

The default value is 'auto' which indicates that MATLAB chooses the type based on the input to webwrite. If using PostName/PostValue argument pairs, then MATLAB uses 'application/x-www-form-urlencoded' to send the pairs. If using a data argument that is a scalar string or character vector, then MATLAB assumes it is a form-encoded string and sends it as-is using 'application/x-www-form-urlencoded'. If data is anything else, then MATLAB converts it to JSON using jsonencode and uses the content type 'application/json'.

If you specify a MediaType containing 'json' or 'javascript', and data is a character vector, then it is sent as-is. All other types, including scalar strings, are converted using jsonencode.

If you specify 'application/x-www-form-urlencoded', then PostName/PostValue pairs are sent form-encoded. data, if present, must be a string or character vector to be sent as-is.

If you specify a MediaType that contains 'xml', and data is a Document Object Model object (a Java org.apache.xerces.dom.DocumentImpl), then it is converted to XML. data, if present, must be a string or character vector to be sent as-is.

If you specify any other MediaType, and data is a string or character vector, then weboptions sends the value as-is.

PostName/PostValue pairs are accepted only for MediaType values 'auto' and 'application/x-www-form-urlencoded', and character vectors are always sent as-is regardless of the MediaType.

You can specify semicolon-separated name=value parameters within the MediaType string, for example, 'application/json; odata=verbose'. Some servers require this format as part of the Content-Type header field in the request.

Example: weboptions('MediaType','application/json') creates a weboptions object that instructs webwrite to encode character vector data as JSON to post it to a web service.

HTTP request method, specified as a string scalar, a character vector, or a matlab.net.http.RequestMethod enumeration as one of these values:

  • 'auto'

    • webread and websave use the HTTP GET method.

    • webwrite uses the HTTP POST method.

  • 'get' for use with the webread and websave functions.

  • 'post' for use with the webread, webwrite, and websave functions.

  • 'put' for use with the webread, webwrite, and websave functions.

  • 'delete' for use with the webread, webwrite, and websave functions.

  • 'patch' for use with the webread, webwrite, and websave functions.

The webread and websave functions put the query into the URL regardless of the RequestMethod. webwrite puts the query into the data regardless of the RequestMethod.

Example: weboptions('RequestMethod','post') creates a weboptions object that instructs webread, websave, or webwrite to use the HTTP POST method of a web service.

Format to form-encode query or post values that represent multiple values, specified as 'csv', 'json', 'repeating', or 'php'. A query or post value contains multiple values if it is

  • A numeric, logical, or datetime vector

  • A character array with more than one row

  • A cell vector, where each element is a numeric, logical, or datetime scalar or a character vector with one row

No other data types or dimensions are supported.

This table shows form-encoded conversions for each format, for a query parameter named 'parameter' and a query value of [1 2 3]. The web service specifies the conversion to use.

ArrayFormat Specifier

Form-Encoded Conversion

'csv' (default)

parameter=1,2,3

'json'

parameter=[1,2,3]

'repeating'

parameter=1&parameter=2&parameter=3

'php'

parameter[]=1&parameter[]=2&parameter[]=3

To encode a scalar as a one-element array with the 'json' or 'php' specifiers, place the scalar in a one-element cell array.

Example: weboptions('ArrayFormat','repeating') creates a weboptions object that instructs webread, websave, or webwrite to form-encode any query or post value with multiple values as repeating query parameters.

File name, specified as a string scalar or character vector denoting the name and location of a file containing root certificates. The file must be in privacy-enhanced mail (PEM) format. The location must be in the current folder, in a folder on the MATLAB path, or a full or relative path to a file. The certificates contained in this file are used to validate server certificates for HTTPS connections. Since the security of HTTPS connections depends on the integrity of this file, protect it appropriately. MATLAB does not manage certificates or certificate files, but there are third-party tools available for managing PEM files.

By default when options are not specified, MATLAB validates server certificates using the system-provided certificate store. This is also the behavior if CertificateFilename is set to 'default'.

If CertificateFilename is empty (''), then the validation of the server certificate is turned off. MATLAB only verifies that the domain name of the server certificate matches that of the server.

If you encounter a server certificate validation failure using 'default', then check the connection using your system browser.

If you encounter a connection issue, consider the following:

  • For an expired or revoked server certificate, contact the website owner or server administrator.

  • For a missing Root CA certificate, you can choose one of the following:

    • Add the Root CA certificate to the file denoted by CertificateFilename.

    • Disable certificate validation by setting CertificateFilename to empty ('').

  • For a mismatch between the domain name of the server certificate and the domain name of the server, you can disable this validation by creating a matlab.net.http.RequestMessage object and setting the matlab.net.http.HTTPOptions.VerifyServerName property to false.

Note

These options are temporary workarounds and MathWorks strongly recommends that you resolve the root cause of any server certificate validation failure by using a valid/correct server certificate.

Attributes:

GetAccess

public

SetAccess

public

Version History

Introduced in R2014b

See Also

| | | |

Topics