% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(http/http_client): HTTP client library}

\label{sec:httpclient}

This library provides the four basic HTTP client actions: \verb$GET$,
\verb$DELETE$, \verb$POST$ and \verb$PUT$. In addition, it provides \predref{http_read_data}{3},
which is used by \file{library(http/http_parameters)} to decode \verb$POST$ data in
server applications.

This library is based on \predref{http_open}{3}, which opens a URL as a Prolog
stream. The reply is processed by \predref{http_read_data}{3}. The following
content-types are supported. Options passed to \predref{http_get}{3} and friends
are passed to \predref{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 \qpredref{http_client}{http_convert_data}{4}.

\begin{description}
    \termitem{application/x-www-form-urlencoded}{}
Built in. Converts form-data into a list of \verb$Name=Value$ terms.
    \termitem{application/x-prolog}{}
Built in. Reads a single Prolog term.
    \termitem{multipart/form-data}{}
Processed if \file{library(http/http_multipart_plugin)} is loaded. This
format should be used to handle web forms that upload a file.
    \infixtermitem{\Sbar}{\term{text/html}{}}{\term{text/xml}{}}
Processed if \file{library(http/http_sgml_plugin)} is loaded. See \predref{load_html}{3}
for details and \predref{load_xml}{3} for details. The output is often processed
using \predref{xpath}{3}.
    \infixtermitem{\Sbar}{\term{application/json}{}}{\term{application/jsonrequest}{}}
Processed if \file{library(http/http_json)} is loaded. The option
\verb$json_object(As)$ can be used to return a term \verb$json(Attributes)$
(\arg{As} is \const{term}) or a dict (\arg{As} is \const{dict}).
\end{description}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{http_get}{3}{+URL, -Data, +Options}
Get data from a \arg{URL} server and convert it to a suitable Prolog
representation based on the \verb$Content-Type$ header and plugins.
This predicate is the common implementation of the HTTP client
operations. The predicates \predref{http_delete}{3}, \predref{http_post}{4} and
\predref{http_put}{4} call this predicate with an appropriate
\verb$method(+Method)$ option and ---for \predref{http_post}{4} and \predref{http_put}{4}---
a \verb$post(+Data)$ option.

\arg{Options} are passed to \predref{http_open}{3} and \predref{http_read_data}{3}. Other
options:

\begin{description}
    \termitem{reply_header}{-Fields}
Synonym for \verb$headers(Fields)$ from \predref{http_open}{3}. Provided for
backward compatibility. Note that \verb$http_version(Major-Minor)$
is missing in the new version.
\end{description}

    \predicate[det]{http_delete}{3}{+URL, -Data, +Options}
Execute a \verb$DELETE$ method on the server. Arguments are the same
as for \predref{http_get}{3}. Typically one should pass the option
\verb$status_code(-Code)$ to assess and evaluate the returned status
code. Without, codes other than 200 are interpreted as an error.

\begin{tags}
    \tag{See also}
Implemented on top of \predref{http_get}{3}.
    \tag{To be done}
Properly map the 201, 202 and 204 replies.
\end{tags}

    \predicate[det]{http_post}{4}{+URL, +Data, -Reply, +Options}
Issue an HTTP \verb$POST$ request. \arg{Data} is posted using
\predref{http_post_data}{3}. The HTTP server reply is returned in \arg{Reply},
using the same rules as for \predref{http_get}{3}.

\begin{tags}
    \tag{See also}
Implemented on top of \predref{http_get}{3}.
\end{tags}

    \predicate{http_put}{4}{+URL, +Data, -Reply, +Options}
Issue an HTTP \verb$PUT$ request. Arguments are the same as for
\predref{http_post}{4}.

\begin{tags}
    \tag{See also}
Implemented on top of \predref{http_post}{4}.
\end{tags}

    \predicate{http_patch}{4}{+URL, +Data, -Reply, +Options}
Issue an HTTP \verb$PATCH$ request. Arguments are the same as for
\predref{http_post}{4}.

\begin{tags}
    \tag{See also}
Implemented on top of \predref{http_post}{4}.
\end{tags}

    \predicate[det]{http_read_data}{3}{+Request, -Data, +Options}
Read data from an HTTP connection and convert it according to
the supplied \verb$to(Format)$ option or based on the \verb$Content-type$
in the \arg{Request}. The following options are supported:

\begin{description}
    \termitem{to}{Format}
Convert data into \arg{Format}. Values are:

\begin{shortlist}
    \item \verb$stream(+WriteStream)$)
Append the content of the message to Stream
    \item atom
Return the reply as an atom
    \item string
Return the reply as a string
    \item codes
Return the reply as a list of codes
\end{shortlist}

    \termitem{form_data}{AsForm}
    \termitem{input_encoding}{+Encoding}
    \termitem{on_filename}{:CallBack}
These options are implemented by the plugin
\file{library(http/http_multipart_plugin)} and apply to processing
\verb$multipart/form-data$ content.
    \termitem{content_type}{+Type}
Overrule the content-type that is part of \arg{Request} as a
work-around for wrongly configured servers.
\end{description}

Without plugins, this predicate handles

\begin{description}
    \termitem{application/x-www-form-urlencoded}{}
Converts form-data into a list of \verb$Name=Value$ terms.
    \termitem{application/x-prolog}{}
Converts data into a Prolog term.
\end{description}

\begin{arguments}
\arg{Request} & is a parsed HTTP request as returned by
\predref{http_read_request}{2} or available from the HTTP server's request
dispatcher. \arg{Request} must contain a term \verb$input(In)$ that provides
the input stream from the HTTP server. \\
\end{arguments}

    \predicate[semidet,multifile]{http_convert_data}{4}{+In, +Fields, -Data, +Options}
Multi-file hook to convert a HTTP payload according to the
\textit{Content-Type} header. The default implementation deals with
application/x-prolog. The HTTP framework provides
implementations for JSON (\file{library(http/http_json)}), HTML/XML
(\file{library(http/http_sgml_plugin)})

    \predicate[det]{http_disconnect}{1}{+Connections}
Close down some connections. Currently \arg{Connections} must have the
value \const{all}, closing all connections.

\begin{tags}
    \tag{deprecated}
New code should use \predref{http_close_keep_alive}{1} from
\file{library(http/http_open)}.
\end{tags}

\qpredicate[semidet,multifile]{http}{post_data_hook}{3}{+Term, +Out, +Options}Hook to extend the datatypes supported by the \verb$post(Data)$ option
of \predref{http_open}{3}. The default implementation supports
\verb$prolog(Term)$, sending a Prolog term as \verb$application/x-prolog$.
\end{description}