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 [#:verify-certificate? #t]

Return an open input/output port for a connection to URI. Guile dynamically loads GnuTLS for HTTPS support. See how to install the GnuTLS bindings for Guile in GnuTLS-Guile, for more information.

When verify-certificate? is true, verify the server’s X.509 certificates against those read from x509-certificate-directory. When an error occurs—e.g., the server’s certificate has expired, or its host name does not match—raise a tls-certificate-error exception. The arguments to the tls-certificate-error exception are:

1. a symbol indicating the failure cause, host-mismatch if the certificate’s host name does not match the server’s host name, and invalid-certificate for other causes;
2. the server’s X.509 certificate (see GnuTLS Guile reference in GnuTLS-Guile);
3. the server’s host name (a string);
4. in the case of invalid-certificate errors, a list of GnuTLS certificate status values—one of the certificate-status/ constants, such as certificate-status/signer-not-found or certificate-status/revoked.

Scheme Procedure: http-request uri arg…

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

The following 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.

#:method 'GET

#:body #f

#:verify-certificate? #t

#:port (open-socket-for-uri uri #:verify-certificate? verify-certificate?)

#: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.

If port is false, uri denotes an HTTPS URL, and verify-certificate? is true, verify X.509 certificates against those available in x509-certificate-directory.

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).

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, POST, etc.).

These procedures are variants of http-request specialized with a specific method argument, and have the same prototype: a URI followed by an optional sequence of keyword arguments. See http-request, for full documentation on the various keyword arguments.

Scheme Parameter: x509-certificate-directory

This parameter gives the name of the directory where X.509 certificates for HTTPS connections should be looked for.

Its default value is one of:

• the value of the GUILE_TLS_CERTIFICATE_DIRECTORY environment variable;
• or the value of the SSL_CERT_DIR environment variable (also honored by the OpenSSL library);
• or, as a last resort, "/etc/ssl/certs".

X.509 certificates are used when authenticating the identity of a remote site, when the #:verify-certificate? argument to open-socket-for-uri, to http-request, or to related procedures 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

Scheme Parameter: current-https-proxy

Either #f or a non-empty string containing the URL of the HTTP or HTTPS 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 and https_proxy environment variables.

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