HTTP Client

8.13

HTTP Client🔗

Yanying Wang <yanyingwang1@gmail.com>

(require http-client)

package: http-client

A practical Racket HTTP client for interacting data with HTTP servers.

In case of backwards incompatible updating, you can do the installation with:
- consulting the git commit references as Package Sources:
  raco pkg install "https://github.com/yanyingwang/http-client.git#f1b55669b23c35447c0688ef0495a6abfb7c9fdd"
- using git tags:
  raco pkg install "https://github.com/yanyingwang/http-client.git#v0.0.1"
Releases: https://github.com/yanyingwang/http-client/releases

1 Common Usage Example🔗

1.1 Explicitly request URLs🔗

Request https://httpbin.org/anything/fruits?color=red&made-in=China&price=10 with setting request headers Token: your-token would be like below:

> (http-get "https://httpbin.org"
            #:path "anything/fruits"
            #:data (hasheq 'color "red" 'made-in "China" 'price 10)
            #:headers (hasheq 'Token "your-token"))

1.2 Request nuance URLs🔗

You can define a http-connection, and use it to do requests with modifying some details of it.

1.2.1 Define connections🔗

Predefine a http-connection with presetting url/path/headers/data:

> (define httpbin-org/anthing
      (http-connection "https://httpbin.org/anything"
                       (hasheq 'Content-Type "application/json")
                       (hasheq 'made-in "China" 'price 10)))

1.2.2 Do the requests🔗

Do a GET request with adding path/data/headers to the predefined http-connection:

Get https://httpbin.org/anything/fruits?made-in=China&price=10&color=red with setting request headers to Token: your-token; Another-Token: your-another-token in Racket:

> (http-get httpbin-org/anthing
            #:path "/fruits"
            #:data (hasheq 'color "red")
            #:headers (hasheq 'Another-Token "your-another-token"))

and the preceding code is supported to be written in another way like below:

> (http-bin-org/anthing 'get
                         #:path "/fruits"
                         #:data (hasheq 'color "red")
                         #:headers (hasheq 'Another-Token "your-another-token"))

Do a POST request like

curl -X GET https://httpbin.org/anything/fruits --header "Content-Type: application/application/x-www-form-urlencoded" --header "Token: your-overwritten-token" -d '{"make-in": "China", "price": "10", "color": "red"}'

in Raket:

> (http-post httpbin-org/anthing
             #:path "/fruits"
             #:data (hasheq 'color "red")
             #:headers (hasheq 'Content-Type "application/x-www-form-urlencoded" 'Token "your-overwritten-token"))

Do a POST request with copying and modifying the predefined http-connection’s headers to Content-Type: application/x-www-form-urlencoded:
> (define new-conn
(struct-copy http-connection httpbin-org/anthing
[headers (hasheq 'Content-Type "application/x-www-form-urlencoded")]))
> (http-post new-conn)

2 Reference🔗

2.1 Parameters🔗

parameter
(current-http-client/user-agent) → string?
(current-http-client/user-agent v) → void?
v : string?
= "http-client[your-system-name/your-vm-sytem-type-name/your-racket-version]"

The user agent name used by requesting the HTTP servers.

Added in version 1.0 of package http-client.

parameter
(current-http-client/response-auto) → boolean?
(current-http-client/response-auto v) → void?
v : boolean?
= #t

Set this parameter to #f to disable the auto convertion of the response’s body data. In another word, http-response-body of a http-response will be a raw string if set this parameter to #f.

Changed in version 1.0 of package http-client: renamed from current-http-response-auto

parameter
(current-http-client/pretty-print-depth) → integer?
(current-http-client/pretty-print-depth v) → void?
v : integer?
= 1

This parameter is used by displaying structs of http-connection/http-request/http-response, check pretty-print-depth for its implement details.

Added in version 1.0 of package http-client.

Examples:

> (define conn1
    (http-connection "https://httpbin.org/anything"
                     (hasheq 'Content-Type "application/json" 'Accept "application/json")
                     (hasheq 'made-in "China" 'price 10)))
> (current-http-client/pretty-print-depth)
1
> conn1
#<http-connection "https://httpbin.org/anything" headers: '#hasheq((...) (...)) data: '#hasheq((...) (...))>
> (current-http-client/pretty-print-depth 2)
> conn1
#<http-connection "https://httpbin.org/anything" headers: '#hasheq((Accept . "application/json") (Content-Type . "application/json")) data: '#hasheq((made-in . "China") (price . 10))>

parameter
(current-http-client/debug) → boolean?
(current-http-client/debug v) → void?
v : boolean?
= #f

Show debug log or not.

Added in version 1.0.1 of package http-client.

2.2 Structs🔗

The displaying of HTTP client strcuts is controlled by current-http-client/pretty-print-depth.

struct
(struct http-connection (url headers data))
  url : string?
  headers : hasheq
  data : hasheq

Construct a http-connection instance and use it later by such as http-get when you’re requesting same website with nuance path/data/headers, check Request nuance URLs for usage examples.

struct
(struct http-response (request code headers body))
  request : http-request?
  code : number?
  headers : hasheq
  body : hasheq

You will get a http-response struct instance if you’re doing a request such as using http-get.

struct
(struct http-request (url method headers data))
  url : string?
  method : symbol?
  headers : hasheq
  data : hasheq

Mostly, http-request is included in the http-response instance.

2.3 Requests🔗

procedure
(http-get conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-post conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-head conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-options conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-put conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-delete conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)
procedure
(http-patch conn
[ #:path path
#:data data
#:headers headers]) → http-response?
  conn : (or/c string? http-connection?)
  path : string? = ""
  data : hasheq = (hasheq)
  headers : hasheq = (hasheq)

Procedures to do the http requests.

procedure
(http-do method
conn
[ #:data data
#:path path
#:headers headers]) → http-response?
  method : symbol?
  conn : http-connection?
  data : hasheq = (hasheq)
  path : string? = ""
  headers : hasheq = (hasheq)

The low level function to do the http requests.

3 Others🔗

3.1 Bug Report🔗

Please go to github and create an issue for this repo.

3.2 TODOs🔗

make #<request GET "https://geoapi.qweather.com/v2/city/lookup?gzip="> to be shown as #<request GET "https://geoapi.qweather.com/....."> if it’s too long.
global param of debug mode to show request and response log msg just like the ruby faraday.
make param of hasheq can also be alist and dict data.

3.3 Change Logs🔗

define a global param for pretty-print-depth for write-proc to show customized depth. –2021/02/26
fix get urls with params will raise error and enhance docs. –2021/02/26
fix additional / and ? added in the url sometimes. –2024/06/26
show debug log. –2024/06/26