section(3,'2.1',swi('/doc/packages/http.html'))

2.1 Library http/http_open -- Simple HTTP client

See also: - xpath/3
- http_get/3
- http_post/4

This library provides a light-weight HTTP client library to get the data from a URL. The functionality of the library can be extended by loading two additional modules that acts as plugins:

library(http/http_chunked): Loading this library causes http_open/3 to support chunked transfer encoding.
library(http/http_header): Loading this library causes http_open/3 to support the POST method in addition to GET and HEAD.

Here is a simple example to fetch a web-page:

?- http_open('http://www.google.com/search?q=prolog', In, []),
   copy_stream_data(In, user_output),
   close(In).
<!doctype html><head><title>prolog - Google Search</title><script>
...

The example below fetches the modification time of a web-page. Note that Modified is '' if the web-server does not provide a time-stamp for the resource. See also parse_time/2.

modified(URL, Stamp) :-
        http_open(URL, In,
                  [ method(head),
                    header(last_modified, Modified)
                  ]),
        close(In),
        Modified \== '',
        parse_time(Modified, Stamp).
close(In).

[det]http_open(+URL, -Stream, +Options)

Open the data at the HTTP server as a Prolog stream. URL is either an atom specifying a URL or a list representing a broken-down URL compatible to parse_url/2. After this predicate succeeds the data can be read from Stream. After completion this stream must be closed using the built-in Prolog predicate close/1. Options provides additional options:

authorization(+Term)

Send authorization. Currently only supports basic(User,Password). See also http_set_authorization/2.

final_url(-FinalURL)

Unify FinalURL} with the final destination. This differs from the original URL if the returned head of the original indicates an HTTP redirect (codes 301, 302 or 303). Without a redirect, FinalURL is unified with the canonical version of URL using:

parse_url(URL, Parts),
parse_url(FinalURL, Parts)

header(Name, -AtomValue)

If provided, AtomValue is unified with the value of the indicated field in the reply header. Name is matched case-insensitive and the underscore (_) matches the hyphen (-). Multiple of these options may be provided to extract multiple header fields. If the header is not available AtomValue is unified to the empty atom ('').

method(+Method)

One of get (default) or head. The head message can be used in combination with the header(Name, Value) option to access information on the resource without actually fetching the resource itself. The returned stream must be closed immediately. If library(http/http_header) is loaded, http_open/3 also supports post. See the post(Data) option.

size(-Size)

Size is unified with the integer value of Content-Length in the reply header.

timeout(+Timeout)

If provided, set a timeout on the stream using set_stream/2. With this option if no new data arrives within Timeout seconds the stream raises an exception. Default is to wait forever (infinite).

post(+Data)

Provided if library(http/http_header) is also loaded. Data is handed to http_post_data/3.

proxy(+Host, +Port)

Use an HTTP proxy to connect to the outside world.

proxy_authorization(+Authorization)

Send authorization to the proxy. Otherwise the same as the authorization option.

request_header(Name=Value)

Additional name-value parts are added in the order of appearance to the HTTP request header. No interpretation is done.

user_agent(+Agent)

Defines the value of the User-Agent field of the HTTP header. Default is =|SWI-Prolog (http://www.swi-prolog.org){\tt\string|}=.

Errors: existence_error(url, Id)

[det]http_set_authorization(+URL, +Authorization)

Set user/password to supply with URLs that have URL as prefix. If Authorization is the atom -, possibly defined authorization is cleared. For example:

?- http_set_authorization('http://www.example.com/private/',
                          basic('John', 'Secret'))

To be done: Move to a separate module, so http_get/3, etc. can use this too.