All Collections
User Guides
UbiFunctions: Using Raw functions
UbiFunctions: Using Raw functions

Learn how to set advanced UbiFunctions

S
Written by Sergio M
Updated over a week ago

IMPORTANT NOTE: ‘Raw functions’ is an advanced option for users with more experience using the UbiFunctions module.

Introduction

By default, UbiFunctions doesn't support custom paths, setting the response code or receive/send custom headers. But, what if your application needs such level of customization?

Raw UbiFunctions offer an advanced level of customization for experienced users. This guide will walk you through how to use these functions to customize endpoint paths, headers and response codes.


What are Raw Functions?

Raw functions allow you to:

  • Use a custom endpoint path in addition to the UbiFunction’s native. This allows executing different routines based on the endpoint path.

  • Receive and respond custom headers. For instance, Authorization headers.

  • Set custom response codes 20X, 40X, 50X, beyond the standard 200 in UbiFunctions. This allows the HTTP client to know the exact result of the execution.

  • Receive and respond custom Content-Type headers for the request body and response: application/json, plain/text, etc.

Enabling Raw Functions

To enable ‘Raw functions’, just toggle the option in the left-side panel of the UbiFunction.

Understanding the Structure of arguments in Raw Functions

Once toggled on, the “args“ argument received in the UbiFunction’s main function will follow the below structure:

{
"path" : "/prv/<YOUR_USERNAME>/<FUNCTION_NAME>/<YOUR_PATH>",
"headers":{
"Content-Type":"plain/text"
},
"body":"A2BF0D"
}

Where:

Key

Value/Type

Example

Path

String representing the Raw UbiFunction's path. Defaults to:

/prv/<YOUR_USERNAME>/<FUNCTION_NAME>
/prv/john-doe/get-measurements/temperature
  • john-doe is the account's username

  • get-measurements is the Raw Ubifunction's name

  • Temperature is the custom path

Headers

Dictionary with all the headers in the request that triggered the function.

{"Content-Type":"plain/text", 
"X-Auth-Token":"BBFF-XXYYZZ"}
  • Content-type is the key describing the content type of the request

  • X-Auth-Token is the Ubidots authentication header

Body

Contains the body with which the request was issued parsed as a string.

"A2BF0D" 

Raw UbiFunctions' path

At the time of making the request to the UbiFunction, its basic URL structure should remain intact, otherwise, the request will point to a different UbiFunction.

For example, say you have the following UbiFunction URL: https://parse.ubidots.com/prv/iot-expo/raw-function/API/Login

With this, you could, for example, execute multiple different logics based on the received path.


Consider that you want to offer three different logic on this endpoint, a login, a logout and a main logic, based on what path is used to make the request. You could make something like:

def main(args):

if args["path"] == "prv/iot-expo/raw-function":
return main_page_logic()
elif args["path"] == "prv/iot-expo/raw-function/API/login":
return login_function(args["body"])
elif args["path"] == "prv/iot-expo/raw-function/API/logout":
return log_out_function()

return {
"status_code": int,
"headers": object,
"body": string,
}

Then, in order to execute the main page logic, all it takes is to make the HTTP request to:

https://parse.ubidots.com/prv/iot-expo/raw-function/

For the login logic:

https://parse.ubidots.com/prv/iot-expo/raw-function/login

And, lastly, for the logout logic:

https://parse.ubidots.com/prv/iot-expo/raw-function/logout

Incoming arguments in the Body key

The contents of the body in the HTTP request are parsed to a string. For example:

  • Consider the following request to the UbiFunction mentioned above:

curl -X POST "https://parse.ubidots.com/prv/iot-expo/raw-function/" \
-H "Content-Type: plain/text" \
-d 24

Note that the number 24 was sent in the body (-d option), however what comes into the arguments to the UbiFunction is actually said number casted to a string, just as:

{"body" : "24"}

  • Suppose now that it is required to send a hexadecimal string such as AFD0E1. You'd have to make the request as:

curl -X POST "https://parse.ubidots.com/prv/iot-expo/raw-function/" \
-H "Content-Type: plain/text" \
-d "AFD0E1"

Then, the body key will look like on Ubidots as:

{"body" : "AFD0E1"}

In summary, you can send any content on the body of the request, as long as it parsed as a string, and the UbiFunction will receive it as so.

Raw UbiFunctions' Response


In the case of a non-raw UbiFunction, when its execution finishes, it will normally reply with its predefined response codes. However, with Raw functions, you can customize the response code, body, and headers at will, that way, the HTTP client making the request will know the precise result of the execution.


The following is the JSON structure to customize the response:

{
"status_code": 200,
"headers": {"Content-Type": "application/json"},
"body": string,
}

Key

Value (possible values)/Type

Example

status_code

Integer number:

200, 20x, 40x, 50x
"status_code" : 200

headers

Dictionary containing response headers

{"Content-Type": "text/plain"}

body

String value.

{"body" : "[INFO] Successful request"}

For example, if the request is valid and the execution successful, the response JSON would be like this:

{
"status_code": 200,
"headers": {"Content-Type": "plain/text"},
"body": "[INFO] Successful request",
}

On the other hand, if based out of your code logic the request is not valid, it should reply a 400 response code, and the JSON response should look like as the follows:

{
"status_code": 400,
"headers": {"Content-Type": "plain/text"},
"body": "[ERROR] Bad Request, please check your request",
}

Other users also found helpful:

Did this answer your question?