2.2 library(http/http_client): 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 dict).

[det]http_get(+URL, -Data, +Options)

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.

[det]http_delete(+URL, -Data, +Options)

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.

[det]http_post(+URL, +Data, -Reply, +Options)

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.

[det]http_read_data(+Request, -Data, +Options)

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.

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.

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

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))

[det]http_disconnect(+Connections)

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).

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

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.