http_client.pl -- HTTP client library

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.

'application/x-www-form-urlencoded': Built in. Converts form-data into a list of Name=Value terms.
'application/x-prolog': Built in. Reads a single Prolog term.
'multipart/form-data': Processed if library(http/http_multipart_plugin) is loaded. This format should be used to handle web forms that upload a file.
text/html|text/xml: Processed if library(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/jsonrequest: Processed if library(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 json).

http_get(+URL, -Data, +Options) is det

Get data from a URL server and convert it to a suitable Prolog representation based on the 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:

reply_header(-Fields): Synonym for headers(Fields) from http_open/3. Provided for backward compatibility. Note that http_version(Major-Minor) is missing in the new version.

http_delete(+URL, -Data, +Options) is det

Execute a 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.

See also: - Implemented on top of http_get/3.
To be done: - Properly map the 201, 202 and 204 replies.

http_post(+URL, +Data, -Reply, +Options) is det

Issue an HTTP 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.

See also: - Implemented on top of http_get/3.

http_put(+URL, +Data, -Reply, +Options)

Issue an HTTP PUT request. Arguments are the same as for http_post/4.

See also: - Implemented on top of http_post/4.

http_patch(+URL, +Data, -Reply, +Options)

Issue an HTTP PATCH request. Arguments are the same as for http_post/4.

See also: - Implemented on top of http_post/4.

http_read_data(+Request, -Data, +Options) is det

Read data from an HTTP connection and convert it according to the supplied to(Format) option or based on the Content-type in the Request. The following options are supported:

to(Format)

Convert data into Format. Values are:

stream(+WriteStream)) Append the content of the message to Stream
atom Return the reply as an atom
string Return the reply as a string
codes Return the reply as a list of codes

form_data(AsForm)

input_encoding(+Encoding)

on_filename(:CallBack)

These options are implemented by the plugin library(http/http_multipart_plugin) and apply to processing multipart/form-data content.

content_type(+Type)

Overrule the content-type that is part of Request as a work-around for wrongly configured servers.

Without plugins, this predicate handles

'application/x-www-form-urlencoded': Converts form-data into a list of Name=Value terms.
'application/x-prolog': Converts data into a Prolog term.

Arguments:

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.

http_convert_data(+In, +Fields, -Data, +Options) is semidet[multifile]

Multi-file hook to convert a HTTP payload according to the Content-Type header. The default implementation deals with application/x-prolog. The HTTP framework provides implementations for JSON (library(http/http_json)), HTML/XML (library(http/http_sgml_plugin))

http_disconnect(+Connections) is det

Close down some connections. Currently Connections must have the value all, closing all connections.

deprecated: - New code should use http_close_keep_alive/1 from library(http/http_open).

http:post_data_hook(+Term, +Out, +Options) is semidet[multifile]

Hook to extend the datatypes supported by the post(Data) option of http_open/3. The default implementation supports prolog(Term), sending a Prolog term as application/x-prolog.