Documentation

Get started Workflows Code samples Reference example

Workflows

[TOC]

Setup and Call

The current version of kodou.io supports the calling of functions after a Setup call to provision the necessary resources. In future versions, the resources will be dynamically allocated.

kodou.io has a web UI for user account management and to search for code. The user types in keywords and phrases to identify the functions they want to find and use. The search page returns a list of results indexed with unique urls. These functions are called Isolated Code Executables “ICE”. Once the user selects one of the functions it is stored in their account for convenience. The url serves as the reference for the function used in kodou.io API calls.

kodou.io is also used to call functions in a set of dependencies. This is called an “Environment”. The user requests a list of desired dependencies (Maven, Pypi, etc.) and kodou.io provisions resources (an environment) to support function calls to those dependencies.

Assuming the endpoint is api.kodou.io, the user will make calls against this endpoint using their API id as a parameter or stored in the HTTP header named Authorization. This header must be used in all kodou API calls to identifiy the account.

Setup call (ICE)

Send a request to the POST https://api.kodou.io/library/setup endpoint.

The user will first call the kodou library/setup API against the endpoint. This call, if successful, will return a token that can be used for any calls to that function.

Using a url the user selected from a code search on the kodou.io web UI, the following is a Setup call using cURL.

curl --request POST \
 --header 'Authorization: Bearer {your API ID eyJhbGciOiJXXXXX....}' \
 --header "Content-Type: application/json" \
 --data '{"url":"https://github.com/antirez/redis.git|91685eeeb1462edfc12da2e079e76bdbeec0eddb|redis/src/sds.c|910|hex_digit_to_int"}' \
 https://api.kodou.io/library/setup

The response will be a Json object with a sessionid field.

{
	"error": false,
    "sessionid": "eyJ0eXAiO..."
}

Function call (ICE)

Send a request to the POST https://api.kodou.io/library/call endpoint.

The function calls will require the Authorization header and a Json payload with the sessionid field, a timeout field, and an args field, a sub-object with the function arguments as fields.

Protocol Buffers (PB) can be used for arguments as well with the https://api.kodou.io/library/callpb endpoint.

The sessionid value serves as a proxy for the function url in the Setup phase. Call this function using the library/call API. The request includes the ‘Authorization’ header, and a Json payload with the sessionid, a timeout value, and an object named args of the function arguments. In the example below, ...hex_digit_to_int accepts one argument named c and returns an integer.

curl --request POST \
 --header 'Authorization: Bearer {your API ID eyJhbGciOiJXXXXX....}' \
 --header "Content-Type: application/json" \
 --data '{"sessionid": {from the Setup call}, "timeout":"20000", "args":{"c": "A"}}'
 https://api.kodou.io/library/call

The http response is a Json object with the function return value like the following:

{
    "return": {
    	"error": false,
        "value": "15"
    }
}

Setup call (Environment)

Send a request to the POST https://api.kodou.io/environment/java/setup endpoint.

The user will first call the kodou environment/java/setup API against the endpoint and supply the set of dependencies requested.

This request, if successful, will return a token that can be used for calls against those dependencies.

The following is a Setup call using cURL where the Google Guava dependency is desired.

curl --request POST \
 --header 'Authorization: Bearer {your API ID eyJhbGciOiJXXXXX....}' \
 --header "Content-Type: application/json" \
 --data '{ "dependencies": [{"groupId":"com.google.guava", "artifactId":"guava","version":"25.0-jre"}] }' \
 https://api.kodou.io/environment/java/setup

The response will be a Json object with a sessionid field.

{
	"error": false,
    "sessionid": "eyJ0eXAiO..."
}

Function call (Environment)

Send a request to the POST https://api.kodou.io/environment/kompose endpoint.

kompose is one of the commands of kodou.io. It supports composing function calls using constructs such as Pipes.

The function calls will require the Authorization header and a Json payload with the sessionid field, a timeout field, and other fields (see the other documentation).

The sessionid value serves as a proxy for the resources in the Setup phase. The request includes the ‘Authorization’ header, and a Json payload with the sessionid, a timeout value, and other objects, in this case named pipeline, of function composition. In the example below, Double.valueOf( "1001.1" ) is Piped into another function Double("101.1").compareTo, returning the value -1 (int). Note, to simplify the example we used well-known Java functions.

curl --request POST \
 --header 'Authorization: Bearer {your API ID eyJhbGciOiJXXXXX....}' \
 --header "Content-Type: application/json" \
 --data '{"sessionid": {from the Setup call}, "timeout":"20000", "pipeline": [
        [
            {	"name": "Double"
            },
            {
                "name": "valueOf",
                "args": [
                    "1001.1"
                ]
            }
        ],
        [
            {
            	"name": "Double",
            	"args": [
            		"101.1"
            	]
            },
            {
            	"name": "compareTo"
            }
        ]
    ]}'
 https://api.kodou.io/environment/kompose

The http response is a Json object with the function return value like the following:

{
    "return": {
    	"error": false,
        "value": -1
    }
}

Binding State

The setup phase can be used to establish values to be used during calls. For example, if you have access keys and other values that are needed for calls you can use kodou’s binding feature, bind-session-arg-names.

Some ICE calls need to carry authentication keys and other values that need to be held secure. During setup you can inject key value pairs into the sessionid and extracted on each call using the bind-session-arg-names Json object. The fields of bind-session-arg-names are named values that will match argument names in a function.

Here is an ICE setup that binds key/values

POST https://api.kodou.io/kodou/library/setup?jwt=eyJXXXXXXX Http/1.1
Content-Type: application/json

{
    "bind-session-arg-names" : {
        "api_id" : _,
        "api_key" : _,
        "baseTable": _
    },
    "reposSourceURL" : "https://github.com/_" ,
    "repositoryHash" : _ ,
    "fullFileName" : _ ,
    "name" : _,
    "startLine" : _
}

This will return a sessionid with bind-session-arg-names encoded within.

Http Semantics Call

Kodou supports Http semantics in a limited way to allow easier web programming. kodou.io can treat the Http protocol as function-like since it has parameters, Form fields (handled specially), return values, etc. The protocol has poor type options, and therefore has a limited range of possible function signatures.

We provide the library/callhttp mechanism that expects Http Form field parameters for ICE calls.

The Form fields Call

Http Form fields are key/value pairs. A Form may include hidden fields where data can be set, yet remain hidden from the viewer.

We expect a hidden Form field named sessionid with the session id value.

We treat field values either as individual parameters or as a single Json object String. By default all fields are treated as parameters. The default means the fields are the arguments for the ICE call. When used as a jsonstring it binds to the last argument name of the ICE call.

To specify how parameters should be interpeted, provide the optional field ‘formAs’, a hidden field, with the proper setting: formAs=parameters (default), formAs=jsonstring

If the default, parameters, is fine you can leave out ‘formAs’, it will be assumed.

When a form field is submitted we expect the url to have jwt in the query parameters. The form field is in the body urlencoded.

Assuming an ICE setup produced the sessionid, here is an example of calling the ICE with the Form as parameters:

POST https://api.kodou.io/library/callhttp?jwt=eyJXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

sessionid=eyjXXXXXXXXX
&Name=Pam
&Age=30

Again, assuming an ICE setup produced the sessionid, here is an example of calling the ICE with the Form fields in a Json object and used as the last argument.

POST https://api.kodou.io/library/callhttp?jwt=eyJXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

sessionid=eyjXXXXXXXXX
&formAs=jsonstring
&Name=Pam
&Age=30

Datatypes: Http fields to Json.

Http Form fields have limited datatype options. This limits their usage in API function calls. Json values are also limited but of a different range. To help Http values be more useful in function calls we support a limited set of hidden form fields which specify the desired type for the field

Http parameters can either be a set of arguments for a function call, formAs=parameters or can be one aggregated parameter formAs=jsonstring

When formAs is jsonstring we can specify the desired type of the input form for coversion to Json. Each field is assumed to be string unless a hidden field defines the type. These hidden type fields have the prefix jsontype_ followed by the same parameter name.

The types are string, number, and boolean. If left out it is assumed to be string.

In this example we specify Json types for each Form field.

POST https://api.kodou.io/library/callhttp?jwt=eyJXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

sessionid=eyjXXXXXXXXX
&formAs=jsonstring
&jsontype_Name=string
&jsontype_Age=number
&Name=Pam
&Age=30

You are not limited to kodou’s type offerings. For example, a kodou function could support type encoding within the Form field name.
In one specific case to encode an Airtable column type into the name of a Form field.
In the example below the Name field is encoded as a Single String, ss. The Age field is encoded as a Single Number, sn. And the Gender is encoded as a Multiple String, ms. The Airtable has 3 columns with the names of Name, Age, and Gender, with the corresponding column types.

# ICE Call urlencoded

# @name airtable1

POST https://api.kodou.io/library/callhttp?jwt= Http/1.1
Content-Type: application/x-www-form-urlencoded

sessionid=eyjXXXXXXXXX
&formAs=jsonstring
&ss_Name=Kris Kringle
&sn_Age=1000
&ms_Gender=Male

But the most general option for specifying types is to use kodou composition operations to transform values by using other functions. In other words you can transform the primitve types in Http or Json into anything else by applying a function that performs the transformation.

Improve this page