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.
