Usage Guide
Shortcut or Instance?
There are two ways to use HttpCommand
.
- Use one of its shortcut methods (
Get
,Do
,GetJSON
) to execute a single HTTP request and examine the response from the host. When you use a shortcut method,HttpCommand
will create a new, local, instance of itself and then use the instance'sRun
method to send the request and receive the response, then exit thereby destroying the local instance. This is generally fine when your requests are independent of one another and do not require any state to be maintained across requests. - Create an instance of
HttpCommand
using⎕NEW
or theNew
shared method, set whatever parameters are necessary, execute theRun
method, and examine the response from the host. Creating an instance ofHttpCommand
and using theRun
method to send the request and receive the response will persist the instance such that state information like connection information and HTTP cookies will be retained across requests.
HttpCommand
's Result
The result of the Run
method is a namespace containing information related to the result of the request. The display format (⎕DF
) of the result presents some useful information.
⊢r ← HttpCommand.Get 'https://www.dyalog.com'
[rc: 0 | msg: | HTTP Status: 200 "OK" | ⍴Data: 20571]
r
is the namespace resultr.rc
isHttpCommand
's numeric return code. 0 meansHttpCommand
was able to create and send the request to the host, send it, and receive and process the response.Ifrc
is less than 0, it means there was some problem either composing/sending the request or processing the response.Ifrc
is greater than 0, it is the Conga return code and generally means that Conga encountered something unexpected. More information aboutrc
can be found here.r.msg
is a (hopefully meaningful) message describing whatever the issue was ifr.rc
is non-zero.r.HttpStatus
is the numeric HTTP status code returned by the host. A status code in the range 200-299 indicates a successful HTTP response with 200 being the most common code.r.HttpMessage
is the HTTP status message returned by the host.r.Data
is the payload of the response, if any, returned by the host. The result namespace contains other elements which are described in detail on the Request Results, Operational Results, and Response Results pages.
Typical Use in Code
Typical use of HttpCommand
might follow this pattern.
resp ← HttpCommand.Get 'some-url'
:If resp.IsOK ⍝ use the IsOK function from the result namespace
⍝ code to handle bad request
:Else
⍝ code to process the response
:EndIf
If you expect to make several HttpCommand
calls, you may want to create an instance and then update the necessary settings and execute the Run
method for each call. This is particularly useful when the requests are made to the same host as the connection to the host will be kept open, unless the host itself closes it.
hc←HttpCommand.New 'get' ⍝ here we expect all requests to be HTTP GET
urls←'url1' 'url2' 'url3'
:For url :In urls ⍝ loop over the URLs
hc.URL←url ⍝ set this URL
resp←hc.Run
:If resp.IsOK
⍝ process the response
:Else
⍝ process the exception/error
:EndIf
:EndFor
Content Types
👉 If your HTTP request has a payload and you do not specify the content type, HttpCommand
will attempt to determine whether to use a content type of 'application/json'
or 'application/x-www-form-urlencoded'
.
This may be fine for interactively tinkering in the APL session. But when running HttpCommand
under program control you should explicitly specify the content type for the payload by either setting ContentType
or adding a content-type
header.
The exception to this is when using GetJSON
which is specifically intended to interact with JSON-based web services and will use a default content type of application/json
.
Special Treatment of application/json
Content Type
If you specify a content type of 'application/json'
, HttpCommand
will automatically convert a non-JSON Params
setting to JSON. In the rare case where Params
is an APL character vector that is valid JSON, you should convert it yourself using 1 ⎕JSON
.
Timeout
and Long-running Requests
The default Timeout
setting (10 seconds) is adequate for most requests. There are a couple of patterns of long running requests. Timeout
can be set to a positive or negative number.
- Setting
Timeout
to a positive number means thatHttpCommand
will time out afterTimeout
seconds with a return code (rc
) of 100. Any partial payload received will returned inData
element of the result. - Setting
Timeout
to a negative number means thatHttpCommand
will not time out as long as data is being received. This is useful in the case where a large payload may be received but you are uncertain of how long it will take to receive. If no data is received within a period ofTimeout
seconds,HttpCommand
will time out with a return code (rc
) of 100. Any partial payload received will be returned in theData
element of the result.
Using a negative Timeout
value is useful in the case where a large payload is being received in chunks but has no benefit if the entire payload is sent in one chunk or if the host takes more than |Timeout
seconds to begin sending its response. In that case, you'll need to set |Timeout
to a larger value.
Compressing Response Payload
HttpCommand
can accept and process response payloads that are compressed using either the gzip or deflate compression schemes. To accomplish this, you need to set the accept-encoding
header to 'gzip, deflate'
.