Did you know ... Search Documentation:
http_json.pl -- HTTP JSON Plugin module
PublicShow source

Most code doesn't need to use this directly; instead use library(http/http_server), which combines this library with the typical HTTP libraries that most servers need.

This module adds hooks to several parts of the HTTP libraries, making them JSON-aware. Notably:

Typically JSON is used by Prolog HTTP servers. This module supports two JSON representations: the classical representation and the new representation supported by the SWI-Prolog version 7 extended data types. Below is a skeleton for handling a JSON request, answering in JSON using the classical interface.

handle(Request) :-
      http_read_json(Request, JSONIn),
      json_to_prolog(JSONIn, PrologIn),
      <compute>(PrologIn, PrologOut),         % application body
      prolog_to_json(PrologOut, JSONOut),

When using dicts, the conversion step is generally not needed and the code becomes:

handle(Request) :-
      http_read_json_dict(Request, DictIn),
      <compute>(DictIn, DictOut),

This module also integrates JSON support into the http client provided by http_client.pl. Posting a JSON query and processing the JSON reply (or any other reply understood by http_read_data/3) is as simple as below, where Term is a JSON term as described in json.pl and reply is of the same format if the server replies with JSON.

      http_post(URL, json(Term), Reply, [])
See also
- JSON Requests are discussed in http://json.org/JSONRequest.html
- json.pl describes how JSON objects are represented in Prolog terms.
- json_convert.pl converts between more natural Prolog terms and json terms.
Source http_client:http_convert_data(+In, +Fields, -Data, +Options)[multifile]
Hook implementation that supports reading JSON documents. It processes the following option:
Where As is one of term or dict. If the value is dict, json_read_dict/3 is used.
Source is_json_content_type(+ContentType) is semidet
True if ContentType is a header value (either parsed or as atom/string) that denotes a JSON value.
Source json_type(?MediaType) is semidet[multifile]
True if MediaType is a JSON media type. http_json:json_type/1 is a multifile predicate and may be extended to facilitate non-conforming clients.
MediaType- is a term Type/SubType, where both Type and SubType are atoms.
Source http:post_data_hook(+Data, +Out:stream, +HdrExtra) is semidet[multifile]
Hook implementation that allows http_post_data/3 posting JSON objects using one of the forms below.
http_post(URL, json(Term), Reply, Options)
http_post(URL, json(Term, Options), Reply, Options)

If Options are passed, these are handed to json_write/3. In addition, this option is processed:

If As is dict, json_write_dict/3 is used to write the output. This is default if json(Dict) is passed.
To be done
- avoid creation of intermediate data using chunked output.
Source http_read_json(+Request, -JSON) is det
Source http_read_json(+Request, -JSON, +Options) is det
Extract JSON data posted to this HTTP request. Options are passed to json_read/3. In addition, this option is processed:
One of term (default) to generate a classical Prolog term or dict to exploit the SWI-Prolog version 7 data type extensions. See json_read_dict/3.
- domain_error(mimetype, Found) if the mimetype is not known (see json_type/1).
- domain_error(method, Method) if the request method is not a POST, PUT or PATCH.
Source http_read_json_dict(+Request, -Dict) is det
Source http_read_json_dict(+Request, -Dict, +Options) is det
Similar to http_read_json/2,3, but by default uses the version 7 extended datatypes.
Source reply_json(+JSONTerm) is det
Source reply_json(+JSONTerm, +Options) is det
Formulate a JSON HTTP reply. See json_write/2 for details. The processed options are listed below. Remaining options are forwarded to json_write/3.
The default Content-type is application/json; charset=UTF8. charset=UTF8 should not be required because JSON is defined to be UTF-8 encoded, but some clients insist on it.
The default status is 200. REST API functions may use other values from the 2XX range, such as 201 (created).
One of term (classical json representation) or dict to use the new dict representation. If omitted and Term is a dict, dict is assumed. SWI-Prolog Version 7.
Source reply_json_dict(+JSONTerm) is det
Source reply_json_dict(+JSONTerm, +Options) is det
As reply_json/1 and reply_json/2, but assumes the new dict based data representation. Note that this is the default if the outer object is a dict. This predicate is needed to serialize a list of objects correctly and provides consistency with http_read_json_dict/2 and friends.
Source prefer_json(+Accept)[private]
True when the accept encoding prefers JSON.
Source json_status_reply(+Term, -MsgLines, -ExtraJSON) is semidet[private]

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source reply_json_dict(Arg1, Arg2)
Source http_read_json(Arg1, Arg2, Arg3)
Source reply_json(Arg1, Arg2)
Source http_read_json_dict(Arg1, Arg2, Arg3)