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 section Web Server).

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

This document was generated on April 20, 2013 using texi2html 5.0.