Request-related Settings

Request-related settings are settings you use to specify attributes of the HTTP request that HttpCommand will process.

Settings

`Command`

Description	The case-insensitive HTTP command (method) for the request. `Command` is not limited to standard HTTP methods like GET, POST, PUT, HEAD, OPTIONS, and DELETE, but can be any string provided that the host has implemented support for it.
Default	`'GET'`
Example(s)	`h.Command←'POST'`

`URL`

Description	The URL for the request. The general format for `URL` is: `[scheme://][userinfo@]host[:port][/path][?query]` At a minimum the `URL` must specify the host.
Default	`''`
Example(s)	`h.URL←'dyalog.com' h.URL←'https://user:pwd@adomain.com:8080/apath/endpoint?name=Drake`
Details	A URL has the general format: `[scheme://][userinfo@]host[:port][/path][?query]` So, a URL can be as simple as just a host name like `'dyalog.com'` or as complex as `'https://username:password@ducky.com:1234/?id=myid&time=1200'` The only mandatory segment is the `host`; `HttpCommand` will infer or use default information when it builds the HTTP request to be sent. scheme - if supplied, it must be either `'http'`, or `'https'` for a secure connection. If not supplied, `HttpCommand` will use `'http'` unless you have specified the default HTTPS port (443) or provided SSL certificate parameters. userinfo - used for HTTP Basic authentication. HTTP Basic authentication has generally been deprecated, but may still be supported by some hosts. If userinfo is supplied, `HttpCommand` will create a proper Base64-encoded `authorization` header. host - the host/domain for the request port - if not supplied, `HttpCommand` will use the default HTTP port (80) unless the HTTPS scheme is used or certificate parameters are specified in which case the default HTTPS port (443) is used. path - the location of the resource within the domain. If not supplied, it's up to the domain's server to determine the default path. query - the query string for the request. If the HTTP method for the request is `'GET'` or `'HEAD'` and request parameters are specified in `Params`, `HttpCommand` will properly format them and append them to the query string. If you choose to supply query string parameters directly, they should be properly URLencoded. (see `URLencode`)

`Params`

Description	The parameters or payload, if any, for the request. `Params` can be a set of name/value pairs or a character vector that is properly formatted for the `ContentType` or `Command` of the request. See details for more information.
Default	`''`
Example(s)	The following examples are equivalent: `h.Params←(('name' 'dyalog') ('age' 39))` `ns←⎕NS '' ⋄ ns.(name age)←'dyalog' 39 ⋄ h.Params←ns`
Details	If `Params` is not empty, its interpretation is dependent on `Command` and the content type of the request. The content type is determined by the `ContentType` setting or the presence of a `content-type` header. If `Command` is `'GET'` or `'HEAD'`, the request will generally not have a payload in the message body (and hence no specified content type) and `Params` will be URLEncoded if necessary and appended to the query string of `URL`. If `Command` is neither `'GET'` nor `'HEAD'` and no content type has been specified, `HttpCommand` will attempt to infer the content type as follows: If `Params` is a simple character vector and looks like JSON `HttpCommand` will set the content type as `'application/json'`; otherwise it will set the content type to `application/x-www-form-urlencoded'. `Params` will then be processed as described below. Otherwise `HttpCommand` will set the content type to `'application/json'` and `Params` will be processed as described below. If the content type is specified, `Params` is processed based on the content type and inserted as the payload of the request. If the content type is: `'x-www-form-urlencoded'`: `Params` will be formatted using `UrlEncode` unless it already composed completely of valid URLEncoding characters. `'application/json'`: If `Params` is a character vector that is a valid JSON representation, it is left unaltered. Otherwise `Params` will be converted to JSON format using `1 ⎕JSON`. In the case where `Params` is an APL character vector that is also valid JSON, you should convert it to JSON prior to setting `Params`. For example, if you have the character vector `'[1,2,3]'` and you want it treated as a string in JSON and not the numeric array `[1,2,3]`, you should process it yourself using `1 ⎕JSON`. For any other content type, it is the responsibility of the user to format `Params` appropriately for that content type.

`Headers`

Description	The HTTP headers for the request. Specified as one of: a set of name/value pairs. a character vector of of one or more name/value pairs in the form `'name:value'` separated by CRLF (`⎕UCS 13 10`). a vector of character vectors, each in the form `'name:value'`
Default	By default, `HttpCommand` will create the following headers if you have not supplied them yourself: `Host:` the host specified in `URL` `User-Agent: 'Dyalog/HttpCommand 5.0.1'` or whatever the version happens to be `Accept: '/'` If the request content type has been specified, `HttpCommand` will insert an appropriate `content-type` header. If the request has content in the request payload, Conga will automatically supply a `content-length` header.
Example(s)	The following examples are equivalent: `h.Headers←'accept' 'text/html' 'content-type' 'test/plain'` `h.Headers←('accept' 'text/html')('content-type' 'test/plain')` `h.Headers←'accept:text/html',(⎕UCS 13 10),'content-type:text/plain'` `h.Headers←('accept:text/html')('content-type:text/plain')`

`ContentType`

Description	This setting is a convenient shortcut for setting the `content-type` HTTP header of the request. If you happen set both `ContentType` and a `content-type` header, `ContentType` takes precedence.
Default	`''`
Example(s)	`h.ContentType←'application/json; charset=UTF-8'`

`Auth`

Description	This setting is the authentication/authorization string appropriate for the authentication scheme specified in `AuthType`. Used along with `AuthType`, `Auth` is a shortcut for setting the authorization HTTP header for requests that require authentication. If `Auth` is non-empty, `HttpCommand` will create an `'authorization'` header and and set its value to `AuthType,' ',Auth`. If you happen set both `Auth` and an `authorization` header, `Auth` takes precedence.
Default	`''`
Example(s)	`h.Auth←'my-secret-token'` `h.Auth←h.Base64Encode 'userid:password' ⍝ HTTP Basic Authentication` `h.Auth←'userid' 'password' ⍝ HTTP Basic Authentication`
Details	For HTTP Basic Authentication, `Auth` can be set to any of `HttpCommand.Base64Encode 'userid:password'` `'userid' 'password'` `'userid:password'` For the latter two items above: it is permissible to not set `AuthType` as `HttpCommand` will infer the authorization scheme is HTTP Basic. `HttpCommand` will properly format and `Base64Encode` the header value. Alternatively, if you provide HTTP Basic credentials in the `URL` as in `'https://username:password@someurl.com'`, `HttpCommand` will automatically generate a proper `'authorization'` header.

`AuthType`

Description	This setting is used in conjunction with Auth and is a character vector indicating the authentication scheme. Three common authentication schemes are: `'Basic'` for HTTP Basic Authentication `'Bearer'` for OAuth 2.0 token authentication `'Token'` for other token-based authentication schemes such as GitHub's Personal Access Token scheme Other values may be used as necessary for your particular HTTP request.
Default	`''`
Example(s)	`h.AuthType←'Bearer'`
Details	If `AuthType` is not set and `Auth` is set to either a character vector in the form `'userid:password'` or a 2-element vector of character vectors as in `('userid' 'password')` `HttpCommand` will infer the `AuthType` to be `'Basic'`. Note: While authentication schemes are supposed to be case insensitive, some servers are not so forgiving and require the authentication scheme to be appropriately cased.

`Cookies`

Description	`Cookies` is a vector of namespaces, each containing a representation of an HTTP cookie. It contains cookies sent by the host that may be used in a series of requests to the same host. This setting should be considered read-only.
Default	`''`
Example(s)	`(c ← HttpCommand.New 'get' 'github.com').Run` `[rc: 0 \| msg: \| HTTP Status: 200 "OK" \| ⍴Data: 299959]` `≢ c.Cookies` `3` `↑c.Cookies.(Name Host ('DD-MMM-YYYY'(1200⌶)Creation))` `_gh_sess github.com 05-AUG-2022` `_octo github.com 05-AUG-2022` `logged_in github.com 05-AUG-2022`

Name/Value Pairs

Params, for an appropriate content type, and Headers can be specified as name/value pairs. HttpCommand gives you some flexibility in how you specify name/value pairs. You may use:

A vector of depth 2 or ¯2 with an even number of elements.
('name' 'dyalog' 'age' 39)
A vector of 2-element vectors, HttpCommand will treat each sub-vector as a name/value pair.
(('name' 'dyalog') ('age' 39))
A 2-column matrix where each row represents a name/value pair.
2 2⍴'name' 'dyalog' 'age' 39
A reference to a namespace, HttpCommand will treat the variables and their values in the namespace as name/value pairs.
ns←⎕NS '' ⋄ ns.(name age)←'dyalog' 39
Note that the names will be alphabetical in the formatted output.