Overview

HttpCommand is a utility is designed to make it easy for the APL user to send requests to and receive responses from HTTP servers like web servers and web services.

Note

While HttpCommand itself is ⎕IO and ⎕ML insensitive, the examples in this documentation assume an environment of (⎕IO ⎕ML)←1.

Loading `HttpCommand`

HttpCommand is included with your Dyalog APL installation. To bring it into your workspace:

Dyalog APL Version 19.0 and later

      ]import {ns} HttpCommand

or, under program control, do:

      ⎕SE.Link.Import {ns} 'HttpCommand'

where {ns} is an optional namespace name or reference.

Dyalog APL versions before 19.0

      ]load HttpCommand {-target=ns}

or, under program control, do:

      ⎕SE.SALT.Load 'HttpCommand {-target=ns}'

{-target=ns} optionally specifies the namespace in which to load HttpCommand. ns is the namespace name.

Upgrading to the Latest `HttpCommand`

This documentation describes the latest version of HttpCommand, which may be more recent than the version of HttpCommand that came pre-installed with your Dyalog APL. Use HttpCommand.Upgrade upgrade your in-workspace copy of HttpCommand. Note that this only upgrades your in-workspace copy of HttpCommand and does not overwrite the version included in your Dyalog installation.

If HttpCommand.Version reports a version earlier than 4.0.14, HttpCommand.Upgrade will need to be run twice to upgrade to the latest version.

HttpCommand.Upgrade does not work with Classic interpreters. See Upgrade for more information.

For example, HttpCommand version 3.4 may be found in Dyalog version 18.0.

      ]load HttpCommand
#.HttpCommand
      HttpCommand.Version
 HttpCommand  3.4  2021-05-28 
      HttpCommand.Upgrade
0   
      HttpCommand.Version  ⍝ verify that we upgraded to v4.0.14
 HttpCommand  4.0.14  2022-09-04 
      HttpCommand.Upgrade  ⍝ now upgrade to v5
0  Upgraded to HttpCommand 5.6.0 2024-03-17 from HttpCommand 4.0.14 2022-09-04

Note

When deploying HttpCommand as a part of your application, you should save a copy with your application to ensure you know precisely what version of HttpCommand is being used. You don't want to dynamically load or upgrade HttpCommand in your application.

`HttpCommand` is Available as a Tatin Package

Tatin is a package manager for APL-based packages. HttpCommand is available as a Tatin package. If you have the Tatin client installed, you can load HttpCommand using:

      ]TATIN.LoadPackages HttpCommand

The Tatin client will be included in your Dyalog installation beginning with Dyalog version 19.0. For earlier versions of Dyalog, refer to the Tatin website for instructions on installing the Tatin client.

Load Once, Use Often

It is strongly recommended that you save your own copy of HttpCommand in your application rather than dynamically loading or upgrading it at runtime. In particular, it is bad practice to repeated load HttpCommand as this may cause Conga to reinitialize each time HttpCommand is loaded and may interfere with other components of your application that also use Conga. If HttpCommand is being used within your application (as opposed to ad hoc usage in your APL session) it is recommended that all Conga-using components refer to the same Conga namespace. See HttpCommand and Conga

Typical Usage Patterns

HttpCommand is implemented as a Dyalog class and its typical usage pattern is:

Create an instance of the HttpCommand class using the function HttpCommand.New
instance ← HttpCommand.New ''
Set fields (settings) appropriate to describe the request
Send the request
Examine the response result

For example:

      cmd←HttpCommand.New ''   ⍝ create an instance
      cmd.Command←'get'        ⍝ specify the HTTP method 
      cmd.URL←'www.dyalog.com' ⍝ specify the URL

      ⊢response←cmd.Run        ⍝ send the request
[rc: 0 | msg: "" | HTTP Status: 200 "OK" | ⍴Data: 21060]

      50↑response.Data         ⍝ examine the response payload
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Trans

The result of HttpCommand.Run is a namespace containing information about the response from server. The display format for the namespace gives some useful information about the success of the request. The server's response data, also known as the content or payload, is found in the Data element of the namespace.

HttpCommand has several "shortcut" shared methods to perform common operations. For instance, the above example can be accomplished by using HttpCommand.Get.

      50↑(HttpCommand.Get 'www.dyalog.com').Data
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Trans

Philosophy

HttpCommand has been designed to be easy to integrate into your application by having a small footprint (it's a single class) and making almost no assumptions about the environment in which you'll use it. HttpComand attempts to use sensible default values for request settings while still giving you full control should you need it. HttpCommand's feature set has expanded over time as new use cases and feature requests have arisen. We expect this trend to continue and encourage you to submit feature requests or report any bugs via GitHub.

This documentation should provide sufficient information to use HttpCommand to make most HTTP requests. In some cases, some further knowledge of HTTP may be necessary. This documentation does not attempt to be an exhaustive HTTP reference.

Dyalog Classes

HttpCommand is implemented as a Dyalog class. While it's not necessary to have an in-depth knowledge of Dyalog classes, it is useful to understand a couple basic concepts. A class can have "shared" methods and settings (known as fields) and "instance" methods and settings. For instance, the "shortcut" methods like Get, GetJSON, Do and New are shared methods whereas the instance methods like Show and Run are only available in an HttpCommand instance. Similarly, Debug and CongaPath are shared settings whereas URL and Command are instance settings. We will attempt to make the distinction between shared and instance references throughout this documentation.

Use of Conga

HttpCommand uses Conga, Dyalog's TCP/IP utility library, for communication. Conga is installed as a part of Dyalog APL. By default HttpCommand will attempt to locate and use the installed Conga. Conga consists of two parts:

Two shared library files that are specific to the operating system and implement the low-level communications and security interfaces.
An APL object that implements a cross-platform interface to the shared libraries. The object will be either the DRC namespace or an instance of the Conga.LIB class. For the purposes of this document we will refer to this object as the Conga API.

See HttpCommand and Conga for more information on how HttpCommand interacts with Conga. See Integrating HttpCommand for more information on how to package Conga and HttpCommand in a distributed application.

If your application has other components that also use Conga, we recommend that you use the "multiple roots" feature of the Conga namespace:

Copy the Conga namespace from the conga workspace.
'Conga' #.⎕CY 'conga'
Set HttpCommand.CongaRef setting to refer to the Conga namespace.
HttpCommand.CongaRef←#.Conga
Similarly configure the other Conga-using components to refer to the Conga namespace.
Now each component can create their own Conga "root" using Conga.Init.
HttpCommand does this for you automatically.