HTTP Client

8.0

top ← prev up next →

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:
- Consulting the git commit references as the Package Sources to do the installation:
  raco pkg install "https://github.com/yanyingwang/http-client.git#f1b55669b23c35447c0688ef0495a6abfb7c9fdd"
- Installing with 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 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 previous code is supported to be written in another way:

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

do a POST request like curl 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))>

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

top ← prev up next →