(web client)
provides a simple, synchronous HTTP client, built on
the lower-level HTTP, request, and response modules.
(use-modules (web client))
Return an open input/output port for a connection to URI. Guile dynamically loads Guile-GnuTLS for HTTPS support.
See the Web site of Guile-GnuTLS, and 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:
host-mismatch
if the
certificate’s host name does not match the server’s host name, and
invalid-certificate
for other causes;
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
.
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).
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.
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:
GUILE_TLS_CERTIFICATE_DIRECTORY
environment
variable;
SSL_CERT_DIR
environment variable (also
honored by the OpenSSL library);
"/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.
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/"