Concepts¶
Plain Function definition¶
Plain functions can be defined as follows:
function function_name(args)
{
return "I am the result";
}
Argument | Description |
---|---|
args |
JSON dictionary of arguments, than might be passed to the function with call (se below) |
Throwing an error¶
To notify the client that error is happened during function/method call, this construction must be called:
throw new Error(error_code, error_message)
// for example
throw new Error(404, "No such hero!")
Asynchronous Functions¶
EcmaScript 8 states that functions can be defined as asynchronous.
The API allows that with the async
/ await
keywords:
async function test(args) {
// wait for one second
await sleep(1.0)
// get the user profile
var my_profile = await profile.get();
return "Hello," + my_profile.name;
}
test.prototype.allow_call = true;
POST /call/test/1.0/test
# waits for one, second, gets the profile
> Hello, %username%
REST API¶
Call the plain function¶
Calls the given function server-side, returning its result.
The function must have allow_call = true
to be defined, otherwise the 404 Not Found
will be returned.
← Request¶
POST /call/<application_name>/<application_version>/<function_name>
Argument | Description |
---|---|
application_name |
A name of the application to call the function about, see Application Name |
application_version |
A version of the application to call the function about, see Application Version |
function_name |
Name of the function to call |
Access scope exec_func_call
is required for this request.
→ Response¶
Function response is returned as is.
Response | Description |
---|---|
200 OK |
Everything went OK, result follows. |
404 Not Found |
No such function |
custom errors | Function may throw errors with custom codes for the client application to process |
WebSocket API¶
Open a new Session¶
To open a new session, a new WebSocket connection on this location should be established:
WebSocket connection¶
WEBSOCKET /session/<application_name>/<application_version>/<class_name>
Argument | Description |
---|---|
application_name |
A name of the application to call the function about, see Application Name |
application_version |
A version of the application to call the function about, see Application Version |
class_name |
Name of the Construction Function to be used on this session |
args |
JSON dictionary of arguments that will be passed as args argument to the Construction Function |
Access scope exec_func_call
is required for this request.
Note
For the session to be successfully be opened, a Constructor Function with name class_name
should exists, and
should have allow_session = true
to be defined:
function Test(args) {}
Test.allow_session = true;
Communication protocol¶
JSON-RPC is used as transport protocol to call the methods of the session, and get the responses.
Call a method¶
To call a method, a request named call
should be sent.
Argument | Description |
---|---|
method_name |
Name of method to be called. |
arguments |
JSON dictionary of arguments that will be passed as args argument to method |
Example of calling a method:
-> {"jsonrpc": "2.0", "method": "call", "params": {"method_name": "test", "arguments": {}}, "id": 1}
<- {"jsonrpc": "2.0", "result": "Testing!", "id": 1}
function Test(args) {}
Test.prototype.test = function(args) {
return "Testing!";
};
Test.allow_session = true;
Note
Methods don’t need allow_call
since all public method of the Constructor function are allowed to call.
To make the method private, start its name with underscore.
“released” method¶
If the session needs to run some code once the connections is lost, a method released
could be defined:
Test.prototype.released = function(args) {
log("I am being released");
};
It will be called automatically upon session being closed. This method cannot be called manually, and should return no result, as it will be ignored. Also, this method allowed to be asynchronous.
Standard API¶
Along with standard Javascript functions, several are added by the API.
Error(code, message)
See Throwing an error.
Argument Description code
The code indicating the problem. message
Error description log(message)
To issue a log message, use
log(message)
Argument Description message
Log message -
Delays the execution for some time.
Argument Description delay
Time for delay in seconds
web¶
An object to access to the internet
config¶
An object to access to the ../config
store¶
An object to access to the ../store
-
Returns the configuration of the given Store
Argument Description name
Store name store.new_order(store, item, currency, amount, component)
Places a new order in the Store. Returns the new order id.
Argument Description store
Store name item
Item name currency
Currency name amount
Items amount component
Component -
Updates the given order. No additional documentation so far.
Argument Description order_id
Order id to update -
Updates all unfinished orders of the user. No additional documentation so far.
profile¶
An object to access to the Profile Service
-
Returns the user’s profile.
Argument Description path
(Optional). Path of the profile to get. If not defined, the whole profile is returned profile.update(profile, [path], [merge])
Updates the user’s profile.
Argument Description profile
A JSON object for the profile to update path
(Optional). Path of the profile to update. If not defined, the whole profile is updated merge
(Optional). If true (default), the JSON objects of existing profile and updated one are mixed, otherwise the old object is replaces -
Search for user profiles with JSON Database Query.
Argument Description profile
JSON Database Query limit
(Optional) Limit number of resulting profiles, default is 1000. A result is a JSON object:
{ "results": { "1": { "profile": { ... profile object ... } }, "12": { "profile": { ... profile object ... } }, ... }, "total_count": <total amount of profiles found> }
admin¶
An object for the administrative purposes. Can be accessed only from a server context, and clients have no ways to access it.
admin.delete_accounts(accounts, [gamespace_only])
Warning
This actions is destructive and should be proceed with caution. Regular database backups are required before using this.
Triggers PERMANENT deletion of certain accounts from all and every service.
Argument Description accounts
A JSON list of accounts to delete gamespace_only
(Optional) Keep the account ID and credentials, so the user can still access data from other gamespaces. Default is true. If true, data will be deleted only from current gamespace. If false, ALL USER DATA FROM ALL GAMESPACES WILL BE PERMANENTLY DELETED.