The Web Calls Service is used by webAppOS and some apps to invoke web calls.
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]
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.
GET/POST https://example.org/services/webcalls/someAction?login=user1&ws_token=123456&project_id=user1/myproject.owlgred
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:
to pass a string as a query argument named "argument";
to encode the JSON argument as an URL data string and pass it as the query argument named "json_argument";
or to encode each property of the JSON as a separate query argument in the name=value format, delimited by &.
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:
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&argument=[reference]
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.
Normally, the web call result is a JSON data (application/json). If an error occurred, a JSON object with the "error" property is returned.
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).
?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.
?some=URL&query=string&app_url_name=myapp|user_registered,user_not_registered