On this page:
7.1 URL Utilities
build-url
ok-http-url?
7.2 Header Utilities
in-header-field/  c
header-field/  c
check-header-field
header-field-list-update
7.3 Request Utilities
method/  c
request/  json
request/  form-urlencoded
request/  multipart
8.12

7 Utilities🔗ℹ

7.1 URL Utilities🔗ℹ

 (require http123/util/url) package: http123-lib

procedure

(build-url base-url    
  path-part ...    
  [#:query query])  url?
  base-url : (or/c url? string?)
  path-part : (or/c string? path/param?)
  query : (listof (cons/c symbol? (or/c #f string?))) = null
Builds a new url structure by extending base-url with the given path-parts and query parameters.

Each path-part is added to the end of base’s existing path. If path-part is a string, it is first split on / characters, "." and ".." segments are converted to 'same and 'up, respectively, and then each segment is wrapped in a path/param with no parameters. Note that the path-part strings are not decoded—for example, the path-part value "%2F" does not represent a one-character segment; it represents a three-character segment that gets encoded as %252F when the URL is converted to a string.

The path is then simplified as follows: 'up and 'same segments are collapsed unless doing so would delete parameters, and empty path segments are removed except that an empty segment is allowed at the end of the path. (An empty segment at the end corresponds to a URL written with a final /.)

The query is appended to the end of base-url’s existing query arguments.

procedure

(ok-http-url? v)  boolean?

  v : any/c
Returns #t if v is a URL structure (url?) that satisfies the following constraints, #f otherwise. The constraints are:
  • the scheme is "http" or "https" (compared case-insensitively)

  • the user field is absent (#f)

  • the host field is present

  • the path is marked as absolute

Examples:
> (ok-http-url? (string->url "http://racket-lang.org/"))

#t

> (ok-http-url? (string->url "http://ryanc@racket-lang.org/"))

#f

> (ok-http-url? (string->url "ftp://mirror.racket-lang.org/"))

#f

> (ok-http-url? (string->url "somewhere/out-there.html"))

#f

7.2 Header Utilities🔗ℹ

 (require http123/util/header) package: http123-lib

value

in-header-field/c : contract?

 = 
(or/c string?
      bytes?
      (list/c (or/c symbol? string? bytes?)
              (or/c string? bytes?)))
Represents the forms that a user may supply a header field as an argument (for example, the header argument to request).

Examples:
"Accept-Encoding:   gzip, deflate  "
'(accept-language #"en")
'(#"User-Agent" #"racket-http123/0.1")

value

header-field/c : contract?

 = 
(list/c (and/c bytes? immutable? ...lowercase-token-rx...)
        (and/c bytes? immutable? ...field-value-rx...))
The canonical representation of a header field. The header field name is represented as an immutable byte string with no upper-case letters. The header field value is represented as an immutable byte string; whitespace is trimmed from the beginning and end of the field value.

Examples:
'(#"accept-encoding" #"gzip, deflate")
'(#"accept-language" #"en")
'(#"user-agent" #"racket-http123/0.1")

procedure

(check-header-field in)  header-field/c

  in : in-header-field/c

procedure

(header-field-list-update base-header 
  ext-header) 
  (listof header-field/c)
  base-header : (listof header-field/c)
  ext-header : (listof header-field/c)

7.3 Request Utilities🔗ℹ

 (require http123/util/request) package: http123-lib

value

method/c : contract?

 = (or/c 'GET 'HEAD 'POST 'PUT 'DELETE 'OPTIONS 'TRACE 'PATCH)
Contract for HTTP methods.

procedure

(request/json method    
  url    
  header    
  json-data    
  [#:write? write?])  request?
  method : method/c
  url : (or/c string? url?)
  header : (listof in-header-field/c)
  json-data : jsexpr?
  write? : boolean? = #f
Creates a request whose body is the JSON represented by json-data. A header field of the form Content-Type: application/json is automatically added to header.

If write? is false, then json-data is immediately converted to a byte string. Otherwise, the request contains a procedure that writes json-data on demand.

procedure

(request/form-urlencoded method    
  url    
  header    
  form-data)  request?
  method : method/c
  url : (or/c string? url?)
  header : (listof in-header-field/c)
  form-data : (listof (cons/c symbol? (or/c #f string?)))
Creates a request whose body is the encoding of form-data using alist->form-urlencoded. A header field of the form Content-Type: application/x-www-form-urlencoded is automatically added header.

procedure

(request/multipart method url header data)  request?

  method : method/c
  url : (or/c string? url?)
  header : (listof in-header-field/c)
  data : 
(listof (let* ([name/c (or/c string? symbol? bytes?)]
               [value/c (or/c string? bytes? procedure?)]
               [in-header/c (listof in-header-field/c)])
          (or/c (list/c name/c value/c)
                (list/c name/c value/c in-header/c)
                (list/c name/c value/c in-header/c '#:filename name/c))))
Creates a request whose body is the encoding of data following the multipart/form-data encoding rules. A header field of the form Content-Type: multipart/form-data with a randomly-generated boundary is automatically added to header.

The data consists of a list of parts. Each part has one of the following forms:
  • (list name value) Consists of a form field name and its corresponding value. Example: (list "language" "en").

  • (list name value header) Like the previous form, but also includes a header that describes this field. Example: (list "subtotal" "€20" '("content-type: text/plain;charset=utf-8"))

  • (list name value header '#:filename filename) Like the previous form, but indicates that the part corresponds to a file with the given filename.