diff --git a/docs/shortcut-methods.md b/docs/shortcut-methods.md index 8c31a81..5886219 100644 --- a/docs/shortcut-methods.md +++ b/docs/shortcut-methods.md @@ -41,55 +41,18 @@ Intermediate positional parameters that are not used should be set to '' ### `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](https://githib.com/dyalog/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. +`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](https://github.com/dyalog/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. - - - - - - - - - - - -
Syntaxr ←{RequestOnly} HttpCommand.GetJSON args
argsEither
  • 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.
rIf 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 -
+|--|--| +| Syntax | `r ←{RequestOnly} HttpCommand.GetJSON args` | +| `args` | One of:| +| `RequestOnly` | (optional) A Boolean indicating:| +| `r` | If `RequestOnly` is| +| Example(s) | These examples assume you have a [`Jarvis`](https://github.com/dyalog/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. diff --git a/source/HttpCommand.dyalog b/source/HttpCommand.dyalog index d27b2ea..789057e 100644 --- a/source/HttpCommand.dyalog +++ b/source/HttpCommand.dyalog @@ -7,7 +7,7 @@ ∇ r←Version ⍝ Return the current version :Access public shared - r←'HttpCommand' '5.8.0' '2024-07-17' + r←'HttpCommand' '5.9.0' '2025-02-24' ∇ ⍝ Request-related fields @@ -190,9 +190,12 @@ ∇ r←{requestOnly}GetJSON args;cmd ⍝ Shared method to perform an HTTP request with JSON data as the request and response payloads - ⍝ args - [Command URL Params Headers Cert SSLFlags Priority] + ⍝ args - [URL] | [Command URL Params Headers Cert SSLFlags Priority] :Access public shared - :If 0=⎕NC'requestOnly' ⋄ requestOnly←¯1 ⋄ :EndIf + :If 0=⎕NC'requestOnly' ⋄ requestOnly←¯1 ⋄ :EndIf + + :If isSimpleChar args ⍝ simple character vector args? + :AndIf (args≡'localhost')≥∧/args∊over lc ⎕A ⋄ args←'GET'args ⋄ :EndIf ⍝ localhost or only alphabetics? →∆EXIT⍴⍨9.1=nameClass cmd←requestOnly New args :If 0∊⍴cmd.Command ⋄ cmd.Command←(1+0∊⍴cmd.Params)⊃'POST' 'GET' ⋄ :EndIf