Executing server code via the REST API

Here is an example of executing server code via the REST API.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/server-code/versions/current/main" \
  -d '{"username": "name_of_my_friend", "password": "password_for_my_friend"}'

• We pass the values for "username" and "password" as the data.
• We call the API with the target endpoint ("main").
• The access token is optional. If it is omitted, Kii Cloud interprets the server code as being executed by an anonymous user.

This will execute the function "main" in the server code. As you see in the sample server code, two custom parameters are used in the KiiUser.userWithUsername() method. Notice that the code is using the keys ("username" and "password") when fetching the corresponding values.

The response will be like the followings:

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Access-Control-Allow-Origin: *
< X-Step-count: 3
< X-Environment-version: 0
< Content-Type: application/json;charset=UTF-8
< Cache-Control: max-age=0
< Content-Length: 27
< Accept-Ranges: bytes
< Date: Tue, 23 Jul 2013 03:57:28 GMT
< X-Varnish: 1572330455
< Age: 0
< Via: 1.1 varnish
< Connection: keep-alive
<
* Connection #0 to host js-box-tmp.internal.kii.com left intact
{"returnedValue":"name_of_my_friend"}
* Closing connection #0

You can see that the execution result is returned in the "returnedValue" field. Also, the number of the executed steps is returned in the "X-Step-count" header and the version of Node.js on which the server code was executed is returned in the "X-Environment-version" header.

You cannot execute server code by manually executing another server code. If you attempt to do so, you will get an HTTP 409 response with the "OPERATION_NOT_ALLOWED" error.

Data types of return values

Your server code can return other data types as the execution result. Check the following table to see how the execution result is returned to the client (Here we assume that the name of callback function for returning the result is "done" in the asynchronous mode).

Timeout

As described in the Limitations, the timeout occurs when the server code execution time goes over 20000 msec.

When the timeout occurs, Kii Cloud usually returns a 400 response as follows:

{
  "errorCode" : "ENDPOINT_INVOCATION_ERROR",
  "message" : "Error found while executing the developer-defined code",
  "details" : {
    "errorCode" : "EXECUTION_TIMEOUT",
    "message" : "execution timeout. limit=20000ms"
  }
}

If you've set the value to return after the timeout as described in Server code syntax, you will get a 200 response instead of a 400 response. In this case, the value specified in the server code will be set in the _timeoutResponse as follows:

{
  "returnedValue":{
    "_timeoutResponse":{
      "customField": "my_custom_message"
    }
  }
}

You can get the value just like the normal execution result.

Specifying the JavaScript engine

You can specify the version of the JavaScript engine on which server code is executed. The specified version overrides the version set at the server code registration.

Below is an example of specifying the JavaScript engine.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/server-code/versions/current/main?environment-version=6" \
  -d '{"username": "name_of_my_friend", "password": "password_for_my_friend"}'

Specify the JavaScript engine with the environment-version parameter within the URL. See the table below for possible values. If the specified JavaScript engine is unavailable, an error will be returned.

If the environment-version parameter is omitted, the JavaScript engine set for the active version of server code or the default JavaScript engine for Kii Cloud is used.