This package provides two client libraries for accessing HTTP servers.
library(http/http_open)
setup_call_cleanup(
http_open(URL, In, []),
process(In),
close(In)).
library(http/http_client)Content-Type of the reply. This
library supports a plugin infrastructure that can register hooks for
converting additional document types.
Content-Type
header.This library defines http_open/3, which opens an URL as a Prolog stream. The functionality of the library can be extended by loading two additional modules that act as plugins:
https is requested using a default SSL context. See the
plugin for additional information regarding security.gzip transfer encoding.
This plugin is lazily loaded if a connection is opened that claims this
transfer encoding.Transfer-encoding: chunked
header.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 '' (the empty atom) 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).
Then next example uses Google search. It exploits library(uri)
to manage URIs, library(sgml) to load an HTML document and library(xpath)
to navigate the parsed HTML. Note that you may need to adjust the XPath
queries if the data returned by Google changes (this example indeed no
longer works and currently fails at the first xpath/3
call)
:- use_module(library(http/http_open)).
:- use_module(library(xpath)).
:- use_module(library(sgml)).
:- use_module(library(uri)).
google(For, Title, HREF) :-
uri_encoded(query_value, For, Encoded),
atom_concat('http://www.google.com/search?q=', Encoded, URL),
http_open(URL, In, []),
call_cleanup(
load_html(In, DOM, []),
close(In)),
xpath(DOM, //h3(@class=r), Result),
xpath(Result, //a(@href=HREF0, text), Title),
uri_components(HREF0, Components),
uri_data(search, Components, Query),
uri_query_components(Query, Parts),
memberchk(q=HREF, Parts).
An example query is below:
?- google(prolog, Title, HREF). Title = 'SWI-Prolog', HREF = 'http://www.swi-prolog.org/' ; Title = 'Prolog - Wikipedia', HREF = 'https://nl.wikipedia.org/wiki/Prolog' ; Title = 'Prolog - Wikipedia, the free encyclopedia', HREF = 'https://en.wikipedia.org/wiki/Prolog' ; Title = 'Pro-Log is logistiek dienstverlener m.b.t. vervoer over water.', HREF = 'http://www.pro-log.nl/' ; Title = 'Learn Prolog Now!', HREF = 'http://www.learnprolognow.org/' ; Title = 'Free Online Version - Learn Prolog ...
false (default true), do not try to
automatically authenticate the client if a 401 (Unauthorized) status
code is received.library(http/http_digest)
is also loaded.curl(1)’s
option‘--unix-socket`.Connection header. Default is close.
The alternative is Keep-alive. This maintains a pool of
available connections as determined by keep_connection/1.
The library(http/websockets) uses Keep-alive, Upgrade.
Keep-alive connections can be closed explicitly using
http_close_keep_alive/1.
Keep-alive connections may significantly improve repetitive requests on
the same server, especially if the IP route is long, HTTPS is used or
the connection uses a proxy.header(Name,Value) option. A
pseudo header status_code(Code) is added to provide the
HTTP status as an integer. See also raw_headers(-List)
which provides the entire HTTP reply header in unparsed representation.get (default), head, delete, post, put
or
patch. 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 post(Data) is provided, the default is post.
Content-Length
in the reply header.Major-Minor, where Major
and Minor are integers representing the HTTP version in the
reply header.end. HTTP 1.1 only supports Unit = bytes.
E.g., to ask for bytes 1000-1999, use the option
range(bytes(1000,1999))raw_encoding('applocation/gzip') the system will not
decompress the stream if it is compressed using gzip.headers(-List).false (default true), do not
automatically redirect if a 3XX code is received. Must be combined with
status_code(Code) and one of the header options to read the
redirect reply. In particular, without status_code(Code) a
redirect is mapped to an exception.infinite).POST request on the HTTP server. Data is
handed to http_post_data/3.proxy(+Host:Port). Deprecated.authorization option.true, bypass proxy hooks. Default is false.infinite.
The default value is 10.User-Agent field of the HTTP
header. Default is SWI-Prolog.
The hook http:open_options/2
can be used to provide default options based on the broken-down URL.
The option
status_code(-Code) is particularly useful to query REST
interfaces that commonly return status codes other than 200
that need to be be processed by the client code.
| URL | is either an atom or string (url) or a
list of parts.
When provided, this list may contain the fields
http_open([ host('www.example.com'),
path('/my/path'),
search([ q='Hello world',
lang=en
])
])
|
error(existence_error(url, Id),Context) is raised if the
HTTP result code is not in the range 200..299. Context has the shape context(Message, status(Code, TextCode)),
where Code is the numeric HTTP code and TextCode
is the textual description thereof provided by the server. Message
may provide additional details or may be unbound.library(http/http_ssl_plugin) is loaded.METHOD keywords. Default are the
official HTTP methods as defined by the various RFCs.Content-encoding as Transfer-encoding
encoding for specific values of ContentType. This predicate
is multifile and can thus be extended by the user.-, possibly
defined authorization is cleared. For example:
?- http_set_authorization('http://www.example.com/private/',
basic('John', 'Secret'))
http and
https URLs for Mode == read.
http_close_keep_alive(_)
closes all currently known keep-alive connections.
:- multifile
http:open_options/2.
http:open_options(Parts, Options) :-
option(host(Host), Parts),
Host \== localhost,
Options = [proxy('proxy.local', 3128)].
This hook may return multiple solutions. The returned options are combined using merge_options/3 where earlier solutions overrule later solutions.
Cookie: header for the current connection. Out
is an open stream to the HTTP server, Parts is the
broken-down request (see uri_components/2)
and Options is the list of options passed to http_open. The
predicate is called as if using ignore/1.
library(http/http_cookie) implements cookie handling on
top of these hooks.Set-Cookie field, Parts is the broken-down
request (see
uri_components/2) and Options
is the list of options passed to http_open.
library(http/http_cookies) implements cookie handling on
top of these hooks.
This library provides the four basic HTTP client actions: GET,
DELETE, POST and PUT. In
addition, it provides http_read_data/3,
which is used by library(http/http_parameters) to decode POST
data in server applications.
This library is based on http_open/3, which opens a URL as a Prolog stream. The reply is processed by http_read_data/3. The following content-types are supported. Options passed to http_get/3 and friends are passed to http_read_data/3, which in turn passes them to the conversion predicates. Support for additional content types can be added by extending the multifile predicate http_client:http_convert_data/4.
Name=Value
terms.library(http/http_multipart_plugin) is loaded.
This format should be used to handle web forms that upload a file.text/html | text/xmllibrary(http/http_sgml_plugin) is loaded. See load_html/3
for details and load_xml/3 for details.
The output is often processed using xpath/3.application/json | application/jsonrequestlibrary(http/http_json) is loaded. The option
json_object(As) can be used to return a term json(Attributes)
(As is term) or a dict (As is dict).Content-Type header and
plugins. This predicate is the common implementation of the HTTP client
operations. The predicates http_delete/3, http_post/4
and
http_put/4 call this predicate
with an appropriate
method(+Method) option and ---for http_post/4
and http_put/4--- a post(+Data)
option.
Options are passed to http_open/3 and http_read_data/3. Other options:
headers(Fields) from http_open/3.
Provided for backward compatibility. Note that http_version(Major-Minor)
is missing in the new version.DELETE method on the server. Arguments are the
same as for http_get/3. Typically
one should pass the option
status_code(-Code) to assess and evaluate the returned
status code. Without, codes other than 200 are interpreted as an error.
POST request. Data is posted using
http_post_data/3. The HTTP
server reply is returned in Reply, using the same rules as
for http_get/3.
PUT request. Arguments are the same as for
http_post/4.
PATCH request. Arguments are the same as for
http_post/4.
to(Format) option or based on the Content-type
in the Request. The following options are supported:
stream(+WriteStream)) Append the content of the message
to Streamlibrary(http/http_multipart_plugin) and apply to processing
multipart/form-data content.Without plugins, this predicate handles
Name=Value terms.| Request | is a parsed HTTP request as returned
by
http_read_request/2 or
available from the HTTP server's request dispatcher. Request
must contain a term input(In) that provides the input
stream from the HTTP server. |
library(http/http_json)), HTML/XML (library(http/http_sgml_plugin))all, closing all connections.
library(http/http_open).post(Data)
option of http_open/3. The
default implementation supports
prolog(Term), sending a Prolog term as application/x-prolog.