Shortcut Methods

These "shortcut" methods make it easier to issue HTTP requests or create an instance of HttpCommand.

Get - issue an HTTP GET request

Get is probably HttpCommand's most-used feature. It issues an HTTP GET request and returns the response from the server. It can be used for many purposes including interacting with web services, downloading files, and returning the contents of web pages.

Syntax	r ←{RequestOnly} HttpCommand.Get args
args	Either a vector of positional settings (only URL is required) URL  Params  Headers  Cert  SSLFlags  Priority Intermediate positional parameters that are not used should be set to '' A namespace containing named variables for the settings for the request. (args ← ⎕NS '').(URL Headers) ← 'someurl.com' ('header1' 'value1')
RequestOnly	(optional) A Boolean indicating: 0 - (default) send the HTTP request and return the response result. 1 - return the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
r	If RequestOnly is 0 - a namespace containing the request response. 1 - the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
Example(s)	args ← ⎕NS ''       args.URL ← 'httpbin.org'       args.Params ← ('name' 'Donald')('species' 'duck')       HttpCommand.Get args [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 339]       HttpCommand.Get 'httpbin.org/get' (('name' 'Donald')('species' 'duck')) [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 339]       1 HttpCommand.Get args GET /get?name=Donald&species=duck HTTP/1.1 Host: httpbin.org User-Agent: Dyalog-HttpCommand/5.0.2 Accept: */*

GetJSON - issue a request to a JSON-based web service

GetJSON is used to interact with web services that use JSON for their request and response payloads. It was originally developed as a convenient way to interact with Jarvis, Dyalog's JSON and REST Service framework. Conveniently, it turns out that there are many web services, including GitHub and Twitter, that use JSON as well.

When Command is something other than GET or HEAD, GetJSON will automatically convert APL Params into JSON format. For GET and HEAD, HttpCommand will URLEncode Params in the query string of the URL. The rationale behind this is that GET and HEAD requests should not have content; therefore Params should be included in the query string of URL and it doesn't make a lot of sense to include JSON in the query string. If you really need JSON in the query string, you can use ⎕JSON to convert Params.

GetJSON will attempt to convert any JSON response payload into its equivalent APL representation.

Syntax	r ←{RequestOnly} HttpCommand.GetJSON args
args	Either a vector of positional settings (Command and URL are required.) Command  URL  Params  Headers  Cert  SSLFlags  Priority Intermediate positional parameters that are not used should be set to '' A namespace containing named variables for the settings for the request.
RequestOnly	(optional) A Boolean indicating: 0 - (default) send the HTTP request and return the response result. 1 - return the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
r	If RequestOnly is 0 - a namespace containing the request response. 1 - the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
Example(s)	These examples assume you have a Jarvis service running at http://localhost:8080 and a endpoint of #.sum ← {+/⍵}.       args ← ⎕NS ''       args.Command ← 'post'       args.URL ← 'localhost:8080/sum'       args.Params ← ⍳1000       ⊢r ← HttpCommand.GetJSON args [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: ⍬]       r.Data 500500       Params ← ('per_page' '3')('page' '1')('sort' 'full_name')       URL ← 'https://api.github.com/orgs/dyalog/repos'       ⊢r ← HttpCommand.GetJSON 'get' URL Params [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 3]       r.Data.full_name  Dyalog/a3s-Linux Dyalog/APLCourse Dyalog/aplssh

Do - issue a generic HTTP request

Do is essentially the same as Get except that you specify the HTTP method (Command) to use.

Syntax	r ←{RequestOnly} HttpCommand.Do args
args	Either a vector of positional settings (Command and URL are required) Command  URL  Params  Headers  Cert  SSLFlags  Priority Intermediate positional parameters that are not used should be set to '' A namespace containing named variables for the settings for the request. (args ← ⎕NS '').(Command URL Headers) ← 'post' 'someurl.com' ('header1' 'value1')
RequestOnly	(optional) A Boolean indicating: 0 - (default) send the HTTP request and return the response result. 1 - return the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
r	If RequestOnly is 0 - a namespace containing the request response. 1 - the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
Example(s)	args ← ⎕NS ''       args.(Command URL) ← 'post' 'httpbin.org/post'       args.Params ← ('name' 'Donald')('species' 'duck')       HttpCommand.Do args [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 465]

New - create a new instance of HttpCommand

New is different than the other shortcut methods in that it returns an instance of HttpCommand. Get, GetJSON, and Do all create an instance, run it, return the response namespace, and upon exit the instance is destroyed.

New can be useful for maintaining state information, like HTTP cookies across multiple requests or keeping the connection to the host open so that subsequent requests to the host are processed without the overhead of re-establishing the connection.

After specifying the settings in the instance, run the Run instance method to execute the request.

Syntax	instance ←{RequestOnly} HttpCommand.New args
args	Either: a vector, possibly empty, of positional settings Command  URL  Params  Headers  Cert  SSLFlags  Priority Intermediate positional parameters that are not used should be set to '' A namespace containing named variables for the settings for the request. (args ← ⎕NS '').(Command URL Headers) ← 'post' 'someurl.com' ('header1' 'value1')
RequestOnly	(optional) A Boolean indicating when Run is executed: 0 - (default) send the HTTP request and return the response result. 1 - return the formatted HTTP request that HttpCommand would send if RequestOnly was 0.
instance	An instance of HttpCommmand.
Example(s)	Use a namespace for the request settings:       args ← ⎕NS ''       args.(Command URL) ← 'post' 'httpbin.org/post'       args.Params ← ('name' 'Donald')('species' 'duck')       cmd ← HttpCommand.New args       cmd.Run [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 465] Create an instance of HttpCommand and set the settings directly:       cmd ← HttpCommand.New '' ⍝ synonym for cmd ← ⎕NEW HttpCommand       cmd.(Command URL) ← 'post' 'httpbin.org/post'       cmd.Params ← ('name' 'Donald')('species' 'duck')       cmd.Run [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 465] Set RequestOnly, display the request that would be sent, then send it       cmd ← 1 HttpCommand.New 'get' 'dyalog.com'       cmd.Run GET / HTTP/1.1 Host: dyalog.com User-Agent: Dyalog-HttpCommand/5.0.4 Accept: */*       cmd.RequestOnly←0       cmd.Run [rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 23127]