7.3 library(http/http_json): HTTP JSON Plugin module

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:
  • http_read_json/2
  • http_read_json/3
  • http_read_json_dict/2
  • http_read_json_dict/3
  • reply_json/1
  • reply_json/2
  • reply_json_dict/1
  • reply_json_dict/2

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