HTTP requests
The :std/net/request library provides an HTTP client interface.
To use the bindings from this module:
(import :std/net/request)
The main HTTP client interface uses a request structure to return results of
HTTP requests. See API documentation for details on making requests.
NOTE: In order to make HTTPS connections the underlying Gambit Scheme
implementation Gerbil is using must be configured with --enable-openssl flag.
Request API
http-get
(http-get url [redirect: #t] [headers: #f] [cookies: #f] [params: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
redirect := boolean telling if client should follow HTTP redirects
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
auth := a list with a keyword head, like [basic: user password]
The http-get procedure executes HTTP GET request to given url and returns an
HTTP request object as result. Request object can be further queried about the
HTTP request results. Procedure signals an error if url is not valid HTTP URL.
The procedure takes optional parameters to specialize the request:
The redirect parameter can be used to tell the client if it should follow
HTTP redirect calls or not. The headers can be used to set extra HTTP headers
for the request. The default headers set by Gerbil are:
Host: url host
Content-Length: binary body length if body is string/bytes
Transfer-Encoding: chunk if body is input-port
The cookies parameter takes an association list of cookie name and value pairs and sets
those on the HTTP request. The params parameter takes association list of
key/value pairs to add as HTTP query params to the request.
Examples
> (http-get "https://cons.io/")
#<request #11>
> (request-status #11)
200
> (http-get "http://cons.io/" redirect: #f)
#<request #13>
> (request-status #13)
301
> (http-get "https://secure.example.com" headers: '(("Authorization" . "Basic QWxhZGRpbjpPcGVuU2VzYW1l")))
http-head
(http-head url [redirect: #t] [headers: #f] [cookies: #f] [params: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
redirect := boolean telling if client should follow HTTP redirects
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
auth := a list with a keyword head, like [basic: user password]
Like the http-get procedure but instead executes HTTP HEAD method on given
url.
http-post
(http-post url [headers: #f] [cookies: #f] [params: #f] [data: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
data := request data given as octet vector or string
auth := a list with a keyword head, like [basic: user password]
Like the http-get procedure but instead executes HTTP POST method on given
url.
http-put
(http-put url [headers: #f] [cookies: #f] [params: #f] [data: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
data := request data given as octet vector or string
auth := a list with a keyword head, like [basic: user password]
Like the http-post procedure but instead executes HTTP PUT method on url.
http-delete
(http-delete url [headers: #f] [cookies: #f] [params: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
auth := a list with a keyword head, like [basic: user password]
Like http-get procedure but instead executes HTTP DELETE method on url.
http-options
(http-options url [headers: #f] [cookies: #f] [params: #f] [auth: #f]) -> request | error
url := a string to tell which URL the HTTP client should connect to
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
auth := a list with a keyword head, like [basic: user password]
Like http-get procedure but instead executes HTTP OPTIONS method on the url.
http-any
(http-any method url [headers: #f] [cookies: #f] [params: #f] [data: #f] [auth: #f]) -> request | error
method := a symbol to define which HTTP method to use, like 'GET or 'PATCH
url := a string to tell which URL the HTTP client should connect to
headers := alist of extra HTTP headers to set in request
cookies := alist of cookie name/value pairs to set in request
params := alist of query param name/value pairs set in request
data := request data given as octet vector or string
auth := a list with a keyword head, like [basic: user password]
Like the other http procedures but allows you to specify your own HTTP method.
Request Objects
request?
(request? req) -> boolean
req := any object
Returns #t if req is an HTTP request object, #f otherwise.
request-url
(request-url req) -> string
req := an HTTP request object
Returns the URL as a string from given req object.
request-status
(request-status req) -> int
req := an HTTP request object
Returns the HTTP status code as integer value from given req object.
request-status-text
(request-status-text req) -> string
req := an HTTP request object
Returns the HTTP status as a text from given req object.
request-headers
(request-headers req) -> alist
req := an HTTP request object
Returns an association list of header name/value pairs from given req object.
request-encoding
(request-encoding req) -> encoding | #f
req := an HTTP request object
Returns the encoding from given req parameter as an string. If no encoding is set the procedure will return #f.
request-encoding-set!
(request-encoding-set! req enc) -> void
req := an HTTP request object
enc := symbol naming used encoding or #f
Sets the HTTP request object req's encoding to value of enc. If set to #f, no conversion is done when accessing requests contents.
NOTE: the value of enc is not validated at all so any bogus value is accepted which will cause code to break later on.
request-content
(request-content req) -> u8vector
req := an HTTP request object
Returns the contents of HTTP request from given HTTP request object req as an unsigned byte vector.
request-text
(request-text req) -> string
req := an HTTP request object
Returns the contents of given HTTP request object req as an string.
request-json
(request-json req) -> json | error
req := an HTTP request object
Returns the request contents of req as an JSON object. Signals an error if request contents isn't valid JSON data.
Examples
> (import :std/net/request)
> (import :std/text/json)
> (http-get "https://jsonplaceholder.typicode.com/todos/1")
#<request #8>
> (json-object->string (request-json #8))
"{\"completed\":false,\"userId\":1,\"title\":\"delectus aut autem\",\"id\":1}"
> (import :std/net/request)
> (import :std/text/json)
> (request-json (http-get "https://www.google.com/"))
*** ERROR IN (console)@10.1 -- read-json: [io-error] Invalid JSON token
--- irritants: #<input-port #11 (string)> <
1>
request-cookies
(request-cookies req) -> list
req := an HTTP request object
Returns the HTTP cookies set in given req HTTP request object. Cookies are given as an list of strings.
request-close
(request-close req) -> void | #f
req := an HTTP request object
Closes the input/output port of given req object. If the port has already been closed the procedure returns #f.
request-port
(request-port req) -> port | #f
req := an HTTP request object
Returns the Input/Output port to be used to access the request data in req. If requests port is already closed, the procedure will return #f.