Web Services

This tutorial describes how to create a Web Application with a HTML/JavaScript front end that run in the users browser and a backend written in Visual Prolog.

The emphasis is on the Visual Prolog back-end, which implement a JSON-RPC Web Service. The HTML/JavaScript code is mainly included to make the example self-contained and to illustrate how font-end code can interact with a Visual Prolog web service.

It is described how the same service can:

• Run as a stand-alone HTTP/HTTPS server
• Run embedded as an ISAPI extension in Microsoft Information Services (IIS)

Notice that web services requires the commercial edition of Visual Prolog. Also notice that this tutorial will not consider SOAP at all.

The tutorial corresponds to the webRPC examples in the commercial edition (IDE: Help ->Install Examples...).

Overview

In this section we will try to describe the overall picture of the entire application and the way it works. What takes place is actually rather complex, but fortunately most of the complexity is handled automatically. An understanding of the overall process including knowledge of some of the complexity will however make it easier to understand what needs to be done and why.

The overall work method of the example application is as follows: The user browses (in a web browser) to the page http://<server>/file/calendar.htm, the server returns the corresponding file to the browser. The browser evaluates the contents of the file, which will result in additional requests for several cascading style scripts (css) files and JavaScript (js) files. Furthermore, calendar.htm contains embedded JavaScript code, which (assisted by the JavaScript in the loaded files) will make remote procedure calls (RPC) to the web server. The server will execute the corresponding procedures and return the result to the browser. Finally, the embedded JavaScript uses the returned data to update the HTML contents of the browser.

The communication between the client and server side is performed by means of the HTTP (or HTTPS) protocol. So on the server side we need an HTTP server, which can both return files and implement remote procedure calls. The program in jsonRpcService_httpApi runs the service as a stand alone HTTP server that both handles file requests and implements the remote procedure calls. The program in jsonRpcService_isApi implements the remote produre calls as an ISAPI plugin, the IIS (Microsoft Internet Information Services) is then configured to handle the file requests and to use the ISAPI for the remote procedure calls.

The stand alone HTTP server is implemented by means of Microsofts HTTP Server API, which can share ports and url's with the Internet Information Services (IIS), such that http://<server>/file, etc can go to our stand alone server while http://<server>/<something> can be handled by the IIS.

JSON & JSON-RPC

The remote procedure calls are implemented in accordance with the JSON-RPC 2.0 Specification specification, which implies that data is encoded in JSON (JavaScript Object Notation) format.

JSON syntax is a sub-set of JavaScript (hence the name): When evaluating a valid JSON text it will be come a corresponding JavaScript object. You should however always call a JSON parser instead of evaluating the text: evaluating text is a security risk, since the text could be "code" rather than "data".

It is not necessary to understand the JSON format in details, because on the client side you will work with JavaScript and on the server side you will work with an object/domain representation of JSON: parsing and writing is left to standard software.

In Visual Prolog JSON is represented by the domain json::jsonValue:

domains
    jsonValue =
        n; % null
        f; % false
        t; % true
        r(real Number);
        s(string String);
        a(jsonValue* Array);
        o(jsonObject Object).

There are only 7 kinds of JSON values null, false, true, a number, a string, an array and an object.

An array is a sequence of JSON values represented as a lins in Visual Prolog.

A JSON object represented by the jsonObject interface in Visual Prolog:

interface jsonObject supports mapM{string Key, jsonValue Value}
...
end interface jsonObject

The interface contains a number of convenience predicates/properties (which have been omitted above), but in essence a jsonObject is simply a map from Key's (names) to JSON values.

Example This code:

J = jsonObject::new(),
J:set_boolean("bbb", true),
J:set_string("sss", "The String"),
J:writeTo(stdio::outputStream)

will produce this output:

{"bbb":true,"sss":"The String"}

writeTo produces a condensed JSON representation suitable interprocess communication, etc. For debugging purposes it can be convenient to pretty print the values:

jsonPrettyPrint::ppObject(stdio::outputStream, J)

will produce this output:

{
    "bbb" : true,
    "sss" : "The String"
}

See also

• JSON
• JSON-RPC 2.0 Specification
• Microsofts HTTP Server API