Next: , Previous: , Up: Web   [Contents][Index]

7.3.8 Web Client

(web client) provides a simple, synchronous HTTP client, built on the lower-level HTTP, request, and response modules.

(use-modules (web client))
Scheme Procedure: open-socket-for-uri uri

Return an open input/output port for a connection to URI.

Scheme Procedure: http-get uri arg...
Scheme Procedure: http-head uri arg...
Scheme Procedure: http-post uri arg...
Scheme Procedure: http-put uri arg...
Scheme Procedure: http-delete uri arg...
Scheme Procedure: http-trace uri arg...
Scheme Procedure: http-options uri arg...

Connect to the server corresponding to uri and make a request over HTTP, using the appropriate method (GET, HEAD, etc.).

All of these procedures have the same prototype: a URI followed by an optional sequence of keyword arguments. These keyword arguments allow you to modify the requests in various ways, for example attaching a body to the request, or setting specific headers. The following table lists the keyword arguments and their default values.

#:body #f
#:port (open-socket-for-uri uri)]
#:version '(1 . 1)
#:keep-alive? #f
#:headers '()
#:decode-body? #t
#:streaming? #f

If you already have a port open, pass it as port. Otherwise, a connection will be opened to the server corresponding to uri. Any extra headers in the alist headers will be added to the request.

If body is not #f, a message body will also be sent with the HTTP request. If body is a string, it is encoded according to the content-type in headers, defaulting to UTF-8. Otherwise body should be a bytevector, or #f for no body. Although a message body may be sent with any request, usually only POST and PUT requests have bodies.

If decode-body? is true, as is the default, the body of the response will be decoded to string, if it is a textual content-type. Otherwise it will be returned as a bytevector.

However, if streaming? is true, instead of eagerly reading the response body from the server, this function only reads off the headers. The response body will be returned as a port on which the data may be read.

Unless keep-alive? is true, the port will be closed after the full response body has been read.

Returns two values: the response read from the server, and the response body as a string, bytevector, #f value, or as a port (if streaming? is true).

http-get is useful for making one-off requests to web sites. If you are writing a web spider or some other client that needs to handle a number of requests in parallel, it’s better to build an event-driven URL fetcher, similar in structure to the web server (see Web Server).

Another option, good but not as performant, would be to use threads, possibly via par-map or futures.

Scheme Parameter: current-http-proxy

Either #f or a non-empty string containing the URL of the HTTP proxy server to be used by the procedures in the (web client) module, including open-socket-for-uri. Its initial value is based on the http_proxy environment variable.

(current-http-proxy) ⇒ "http://localhost:8123/"
(parameterize ((current-http-proxy #f))
  (http-get ""))  ; temporarily bypass proxy
(current-http-proxy) ⇒ "http://localhost:8123/"

Next: , Previous: , Up: Web   [Contents][Index]