Web Calls Service API
Introduction

The Web Calls Service is used by webAppOS and some apps to invoke web calls.

Access URL

The Web Calls Service is accessible via the following URL:

GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]
GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]
GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]
Authentication

Public web calls actions do not require authentication.

Non-public calls require the "login" and "ws_token" arguments in the query string.

Non-static calls also require the "project_id" argument.

Besides, the "app_url_name" parameter can be specified to inform webAppOS and the web call about which web app is making the call. Although, webAppOS will try to infer the web app from other known information (e.g., from the web call location), providing the "app_url_name" explicitly can ensure that webAppOS knows about the web app even when an error occurs.

Example
GET/POST https://example.org/services/webcalls/someAction?login=user1&ws_token=123456&project_id=user1/myproject.owlgred
Sending an argument via the GET method

Since the GET method does not have the data body, the web call argument must be encoded in the query string.

For jsoncall calling conventions, there are 2 options:

Examples
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&argument=[some-string-to-be-passed-as-argument]
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&json_argument=[stringified-JSON-argument]
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&[property1]=[value1]&[property2]=[value2]&...

For webmemcall calling conventions, specify the argument (object reference) via the argument query parameter:

Example
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&argument=[reference]
Sending an argument via the POST method

Data must be sent as POST data encoded in UTF-8.

The following content types are supported:

Content-Type: application/json
Content-Type: multipart/form-data
Content-Type: application/x-www-form-urlencoded

In the latter two cases, the name=value pairs are assumed as properties { name: value } of the JSON object that will be passed to the web call.

Web call result

Normally, the web call result is a JSON data (application/json).  If an error occurred, a JSON object with the "error" property is returned.

Pipe-like usage of the web call result

The web call result can be piped (injected) into HTML files. This is useful when JavaScript is not available, but the desired HTML file contains placeholders, which should be filled with some variable data returned by the web call.

The placeholder must be an HTML comment containing some JSON property name, e.g.:

<!--name-->

Then, if the web call returns a JSON { name: "John" }, the "<!--name-->" placeholder will be replaced by "John".

HTML files can be specified by appending to the query string one of the following:

|[on-success-HTML]
|[on-success-HTML],[on-error-HTML]
^[on-success-HTML]
^[on-success-HTML],[on-error-HTML]

If only [on-success-HTML] is specified, all JSON properties are injected there. Otherwise, either the [on-success-HTML], or the [on-error-HTML] is used depending on whether the returned JSON contains the "error" property.

Both [on-success-HTML] and [on-error-HTML] are just names of .html files located in the web-root directory of the corresponding web app.

If "|" is used, the content of the HTML with injected JSON properties is returned as a response.

If "^" is used, a redirect to some HTML with injected JSON properties is returned. Use "^" to avoid multiple web calls, when the user refreshed the page containing the resulting HTML.  This is in accordance with the Post-Redirect-Get principle (however, "^" works not only for the initial POST, but also GET requests).

Example
?some=URL&query=string|user_registered,user_not_registered

It is recommended to add the "app_url_name" argument to the query string (but before the "|" or "^" symbols), so that webAppOS could find the corresponding on-success/on-error HTML files even when an error occurs.

Example
?some=URL&query=string&app_url_name=myapp|user_registered,user_not_registered