Exchanging data with functions

Base64 encoding

Base64 encoding is used for elements in the input args parameter that can break the internal data structure of the args parameter. Encoding it as Base64 helps ensure that the whole value consists only of readable characters in a 64-character alphabet.

For example:

"eyAicGxhbmV0MSI6Ik1hcnMiLCAicGxhbmV0MiI6Ikp1cGl0ZXIiIH0="

Percent encoding (URL-encoding)

Percent-encoding is widely used in web technology. All 8-bit characters are written as hexadecimal value preceded by a percentage sign (%). This type of encoding is also known as URL-encoding. The function receives the form-urlencoded type data in raw format in the __ce_body parameter.

The Code Engine functions service passes the query parameters as-is (the leading ? is not part of it) into the __ce_query field of the args parameter. This way, the function code receives this parameter in URL-encoded format; for example:

"x%5cb=1%22f4%20and%20"

args parameter set for internal input arguments (__ce_*)

The Code Engine functions service injects reserved input arguments to the args input data.

The following parameters can appear in the args argument depending how the caller provides the request data:

The internal __ce_* parameters cannot be overwritten with request data that is provided in the HTTP request. HTTP calls trying to overwrite fails with status code 400 (Bad Request).

Contents of args parameter if a caller provides request data by query parameters

A function receives query parameter data as key-value pairs in the __ce_query parameter, and is percent-encoded (URL-encoded). Also, each single query parameter is a key-value pair within the decoded format:

Python example of accessing query parameters:

import os
def main(args):
  query_parm_1 = args.get("key", "default_value") # get the value of one query parameter

  try:
    query = args["__ce_query"]  # get all query parms
  except:
    query= "not part of request"

  return {
    "statusCode": 200,
    "body": query,
  }

Node.js example of accessing query parameters:

function main(args) {
  var query_parm_1 = args.key     // get the value of one query parameter
  var query = args.__ce_query     // get all query parameters

  return {
    statusCode: 200,
    "body" : query,
  };
}

module.exports.main = main;

Contents of args parameter if a caller provides request data by header data

A function receives request header data as key-value pairs in the __ce_headers parameter. The key-value pair is converted into a canonical format, regardless of which format that the key is set on the external data interface. For instance, both mykey or MYKEY are converted to Mykey:

Python example of accessing header data:

import os
def main(args):

  try:
    header = args["__ce_headers"]  # get complete header
    # value_1 = args["__ce_headers"]["Key_1"]  # get value of the Header parm with "Key_1"
  except:
    header = "not part of request"

  return {
    "statusCode": 200,
    "body": header,
  }

Node.js example of accessing header data:

function main(args) {
  // var header_parm_1 = args.__ce_headers.Key_1  //get the value of one header parameter
  var header = args.__ce_headers  // get all header parameters

  return {
    statusCode: 200,
    "body" : header,
  };
}

module.exports.main = main;

args parameter from request data of content-type application/json

A function receives the keys and values of the JSON document as dedicated top-level property parameters.

When no value is set for Content-type in the HTTP request, then the Code Engine function uses application/json as the default.

In addition, the JSON payload is made available to the function as-is (as byte array) in Base64-encoded format in the __ce_body parameter.

Python example of accessing application/json input data:

import os
def main(args):
  try:
    body_encoded = args["__ce_body"]  # get complete header (base64 encoded)
    value_1 = args["key_1"]           # get value of the Header parm with "key_1"
  except:
    value_1 = "not part of request"

  return {
    "statusCode": 200,
    "body": value_1,
  }

Node.js example of accessing application/json input data:

function main(args) {
  var body  = args.__ce_body  // get complete request body (base64 encoded)
  var value_1 = args.key_1    // get value of one single key

  return {
    statusCode: 200,
    "body" : value_1,
  };
}

module.exports.main = main;

args parameter from request data of content-type application/octet-stream

A function receives binary data in Base64-encoded format for the __ce_body binary data in the __ce_body parameter:

Python example of accessing application/octet-stream input data:

import os
import base64

def main(args):
  try:
    body = base64.b64decode(args['__ce_body']).decode("utf-8")   # read binary data into the body variable
  except:
    body = "not binary data found"

  return {
    "headers": { "Content-Type": "text/plain" },  # text/plain, if ensured binary data do not conain backslash and double quotes
    "statusCode": 200,
    "body": body,
  }

Node.js example of accessing application/octet-stream input data:

function main(args) {
  var base64EncodedBody = args.__ce_body   // get complete request body (base64 encoded)
  var body = Buffer.from(args.__ce_body, 'base64').toString('utf-8') //  read binary data into the body variable

  return {
    statusCode: 200,
    "body" : body,
  };
}

module.exports.main = main;

args parameter from request data of content-type text/plain

A function receives text type data in Base64-encoded format in the __ce_body parameter:

The function's program logic might need to unescape them to re-create the original data.

Python example of accessing text/plain input data:

import os
def main(args):
  body = args['__ce_body']  # get request body, is text encoded (escaped)

  return {
    "headers": { "Content-Type": "text/plain" },
    "statusCode": 200,
    "body": body,
  }

Node.js example of accessing text/plain input data:

function main(args) {
  var body  = args.__ce_body  // get complete request body (text encoded)

  return {
    statusCode: 200,
    "body" : body,
  };
}

module.exports.main = main;

args parameter from request data of content-type application/x-www-form-urlencoded

A function receives the complete body data in text-encoded format in the __ce_body parameter:

Python example of accessing application/x-www-form-urlencoded input data:

import os
def main(args):
  body = args['__ce_body']  # get request body, is url-encoded (%)

  return {
    "headers": { "Content-Type": "text/plain" },
    "statusCode": 200,
    "body": body,
  }

Node.js example of accessing application/x-www-form-urlencoded input data:

function main(args) {
  var body  = args.__ce_body  //get request body, is url-encoded (%)

  return {
    statusCode: 200,
    "body" : body,
  };
}

module.exports.main = main;

args parameter from request data of content-type application/x-www-form-urlencoded and query parameters

All combinations of mixed data types are possible, but consider that for HTTP requests with URL query parameters and body parameters, the body parameters take precedence over query parameters.

Body value of content-type application/json

Function code must provide the value of the body element as a valid data structure (NodeJs-JSON or Python-Dictionary). The keys and values of the data structure must follow JSON syntax rules so that the Code Engine service can deliver the response data in the application/json HTTP response data section.

Backslashes (\) and double quotation marks (") in the data structure are delivered in text-encoded format in the HTTP response data section.

Python example of an application/json response:

  import os
  def main(args):
    # python dictionary
    result_body = { "key_1" : "myfolder\myFile" }

    return {
      "headers": {
        "Content-Type": "application/json",
      },
      "statusCode": 200,
      "body": result_body,
    }

Node.js example of an application/json response:

function main(args) {
  // JSON data structure
  // Note: Backslash must be text encoded
  result_body =  { "key1" : "myfolder\\myFile"}

  return {
	  statusCode: 200,
	  headers: {
	    'Content-Type': "application/json",
	  },
	  "body" : result_body ,
  };
}
module.exports.main = main;

Body value of content-type application/octet-stream

The result data for the function code must be Base64-encoded before you add it to the result structure.

Python example of an application/octet-stream response:

import os
import base64

def main(args):
  result_body = "myfolder_myFile"
  enc_result_body=base64.encodebytes(result_body.encode()).decode("utf-8").strip()

  return {
    "headers": {
      "Content-Type": "application/octet-stream",
    },
    "statusCode": 200,
    "body": enc_result_body,
  }

Node.js example of an application/octet-stream response:

function main(args) {
  var result_body = "###\unreturned body###\n"
  var buff = new Buffer(result_body , 'utf8');

  return {
    statusCode: 200,
    headers: {
      'Content-Type': "application/octet-stream",
    },
    "body" : buff.toString('base64') ,
  };
}

module.exports.main = main;

Body value of content-type text/plain

Function code must provide the whole response in a single string. The Code Engine functions service does not check the response data; the data is transferred to the caller as provided.

Python example of a text/plain response:

def main(args):
  result_body = "myfolder_myFile"

  return {
    "headers": {
      "Content-Type": "text/plain;charset=utf-8",
    },
    "statusCode": 200,
    "body": result_body,
  }

Body value of content-type application/x-www-form-urlencoded (percent-encoded content)

Function code must help ensure that the response data is URL-encoded before it is added to the result data structure. The Code Engine functions service does not check the response data for correct syntax. The data is transferred to the caller as provided.

Python example of an application/x-www-form-urlencoded response:

import os
def main(args):
  result_body = "myfolder%20myFile"

  return {
    "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    },
    "statusCode": 200,
    "body": result_body,
  }

HTTP header fields

The HTTP header contains all key-value pairs that the function code added to the result data structure.

The Code Engine functions service adds the following key-value pairs:

Header key names are always replied in lowercase.

HTTP status code

The origin of the HTTP status code can be the Code Engine functions service itself or the status code set by the function code. The presence of the header field x-faas-statuscode is the indicator of the origin.

The meaning of the HTTP status code can be read in the Code Engine functions documentation if the x-faas-actionstatus header field is not set. However, if the header field is set, then the logic of the function defines the meaning of the HTTP status code.

Code Engine functions service runs a limited validity check on the response data and content-type, and returns an HTTP status code of 400 if the data format or encoding (generated by the function code) is invalid.

HTTP response data

The HTTP response data on the external data interface are identical as supplied in the result data structure by the function code. Only if the MIME-Type is application/json then the key and values in the provided JSON response are modified. All backslashes and double quotation marks are escaped.

For example, the caller gets application/json response data. The function code that provides the response data is as follows:

import os
def main(args):
  # python dictionary
  result_body = { "key_1" : "myfolder\myFile" }

  return {
    "headers": {
      "Content-Type": "application/json",
      "key" : "sample",
    },
    "statusCode": 200,
    "body": result_body,
  }

The curl client that uses the response statusCcode, the header fields, and the response data, is as follows:

  curl -v -i  https://sample.1kweru2e873.eu-gb.codeengine.appdomain.cloud/
	 -> Response:
	stdout>
   * Host default-encoded-response.1lpigeajq5fg.us-east.codeengine.appdomain.cloud:443 was resolved.
   * IPv6: 2606:4700:90:0:7554:9304:2cbe:8cbf
   * IPv4: 172.65.197.223
   * using HTTP/1.x
   > GET / HTTP/1.1
   > Host: default-encoded-response.1lpigeajq5fg.us-east.codeengine.appdomain.cloud
   > User-Agent: curl/8.8.0
   > Accept: *//*

   * Request completely sent off
   < HTTP/1.1 200 OK
   < content-type: application/json
   < key: sample
   < x-faas-actionstatus: 200
   < x-faas-activation-id: 5cbab12c-5c6e-4000-96cf-0f7fcb42a979
   < x-request-id: e7098271-4780-4893-bbd4-64d4c8d7605e
   < content-length: 13
   { "key_1" : "myfolder\\myFile }* Connection