- 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.
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:
- Make http_read_data/3
convert
application/json and
application/jsonrequest content to a JSON term.
- Cause http_open/3 to accept
post(json(Term))
to issue a POST request with JSON content.
- Provide HTTP server and client utility predicates for reading and
replying JSON:
- Reply to exceptions in the server using an JSON document rather then
HTML if the
Accept header prefers application/json over
text/html.
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),
reply_json(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),
reply_json(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, [])
- [multifile]http_client:http_convert_data(+In,
+Fields, -Data, +Options)
- Hook implementation that supports reading JSON documents. It processes
the following option:
- json_object(+As)
- Where As is one of
term or dict. If
the value is dict,
json_read_dict/3 is used.
- [semidet]is_json_content_type(+ContentType)
- True if ContentType is a header value (either parsed or as
atom/string) that denotes a JSON value.
- [semidet,multifile]json_type(?MediaType)
- 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. |
- [semidet,multifile]http:post_data_hook(+Data,
+Out:stream, +HdrExtra)
- 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:
- json_object(As)
- 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.
- [det]http_read_json(+Request,
-JSON)
- [det]http_read_json(+Request,
-JSON, +Options)
- Extract JSON data posted to this HTTP request. Options
are passed to json_read/3. In
addition, this option is processed:
- json_object(+As)
- 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.
- Errors
- -
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.
- [det]http_read_json_dict(+Request,
-Dict)
- [det]http_read_json_dict(+Request,
-Dict, +Options)
- Similar to http_read_json/2,3,
but by default uses the version 7 extended datatypes.
- [det]reply_json(+JSONTerm)
- [det]reply_json(+JSONTerm,
+Options)
- 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.
- content_type(+Type)
- 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.
- status(+Code)
- The default status is 200. REST API functions may use other values from
the 2XX range, such as 201 (created).
- json_object(+As)
- 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.
- [det]reply_json_dict(+JSONTerm)
- [det]reply_json_dict(+JSONTerm,
+Options)
- 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.
1 
