Skip to main content

🌱 Function

In GreenCloud we operate a system that runs small functions repeatedly. These functions are based around containers that are delivered and executed on remote devices.

A Function can be created using the CLI and is generally not something that is viewed by the end user. The main purpose of the function is to act as a logical construct to represent the software/code that the software developer has written.

When a software developer asks to initiate a function - they will create a task which will also have a related Function to execute.

A Function consists of -:

  1. Name - a non unique character string used to represent the function.

  2. Language - the language that the function is written in.

    At the time of writing GreenCloud supports -:

  • 🔆 GOLANG → go (1.21)

  • 🔆 PYTHON → py (3.12)

  • 🔆 NODEJS → js (18)

  • 🔆 CSHARP → cs (6)

  • 🔆 RUBY → rb (2.7.5)

  • 🔆 RUST → rs (1.7.8)

    We are looking to add C / C++ and WASM in the near future.

Create​

info

Use this endpoint to create a function to use in the GreenCloud system. The response from a succesful call is an HTTP 201 in which the body of the response contains the ID of the newly created function.

tip

When choosing your language 'lang' make sure to use uppercase (this is different to creating a function via the CLI).

When setting your 'type' make sure to use uppercase as well.

Endpoint​

POST
https://api.greencloud.dev/v1/function
https://api.greencloud.dev/v1/function

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue
Content-Typeapplication/jsontrue

Request Body​

KeyExampleRequirements
nameMyFunctionrequired alphanum
descriptionMy function descriptionoptional printascii max=80
tag[tag id, tag id, tag id]optional dive unique alphanum
langGOrequired oneof=GO PY JS CS RB RS
typeDOCKERrequired oneof=DOCKER

Example Request​

{
    "name": "MyFunction",
    "description":"My function description",
    "tag": ['63fe131f02975e4956238b39', '63fe131f02975e4956238b40'],
    "lang": "GO",
    "type": "DOCKER"
}

Example Response​

Status: 201 Created
{
    "id": "63f47d24dab5eb85451f3b61",
}

Edit​

info

Use this endpoint to edit the meta data about a function. You will need to pass the id of the function on the URL. The parameters that you can edit are the name, description and tags of the function.

Endpoint​

PATCH
https://api.greencloud.dev/v1/function/[functionId]
https://api.greencloud.dev/v1/function/[functionId]

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue
Content-Typeapplication/jsontrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Request Body​

KeyExampleRequirements
nameMyFunctionoptional alphanum
descriptionMy function descriptionoptional printascii max=80
tag[tag id, tag id, tag id]optional dive unique alphanum

Example Request​

{
    "name": "MyFunction",
    "description":"My function description",
    "tag": ['63fe131f02975e4956238b39', '63fe131f02975e4956238b40'],
}

Example Response​

Status: 204 No Content
Empty body

Get​

info

If you need to retrieve details about a particular function, use this endpoint by passing the function's ID as a URL parameter. The endpoint will provide you with a list of information related to the function.

Endpoint​

GET
https://api.greencloud.dev/v1/function/[functionId]
https://api.greencloud.dev/v1/function/[functionId]

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Example Request​

Empty body

Example Response​

Status: 200 OK
{
    "name": "MyFunction",
    "description": "My function description",
    "type": "docker",
    "lang": "go",
    "tags": [
        {
            "id": "63ed33eac79248a54ee04831",
            "name": "greencloud",
            "color": "#00ff80"
        }
    ],
    "capabilities": {
        "timeout": 10,
        "cpuCount": 0,
        "memSize": 0,
        "networkLatency": 0,
        "privileged": true
    },
    "metrics": {
        "todaysTasks": 0,
        "pendingTasks": 0,
        "weekTasks": 0,
        "completedTasks": 0
    }
}

List​

info

Use this endpoint to get a list of functions in your GreenCloud account.

Endpoint​

GET
https://api.greencloud.dev/v1/function/list
https://api.greencloud.dev/v1/function/list

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Example Request​

Empty body

Example Response​

Status: 200 OK
[
    {
    id: "6404b3da46551827c611ffe5",
        name: "MyFunction",
        description: "My function description",
        lang: "go",
        tags: [
            {
                id: "63ed33eac79248a54ee04831",
                name: "greencloud",
                color: "#00ff80",
            },
        ],
    createdAt: "1678029786"
    },
    {
    id: "6404b3da46551827c611ffe6",
        name: "MyFunction2",
        description: "My 2nd function description",
        lang: "go",
        tags: [
            {
                id: "63ed33eac79248a54ee04831",
                name: "greencloud",
                color: "#00ff80",
            },
        ],
    createdAt: "1676489715"
    },
]

List By Tag​

info

Use this endpoint to get a list of functions by tag. Note that you need to pass the tag you are interested in as a query parameter. We introduced Tags into GreenCloud as a means to be able to better manage your GreenCloud assets. Please see the Tag documentation for more details.

Endpoint​

GET
https://api.greencloud.dev/v1/function/list?tag=[tagId]
https://api.greencloud.dev/v1/function/list?tag=[tagId]

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Request Parameters​

ValueExampleRequired
tag id63f47d24dab5eb85451f3b61true

Example Request​

Empty body
Status: 200 OK
[
    {
    id: "6404b3da46551827c611ffe5",
        name: "MyFunction",
        description: "My function description",
        lang: "go",
        tags: [
            {
                id: "63ed33eac79248a54ee04831",
                name: "greencloud",
                color: "#00ff80",
            },
        ],
    createdAt: "1678029786"
    },
    {
    id: "6404b3da46551827c611ffe6",
        name: "MyFunction2",
        description: "My 2nd function description",
        lang: "go",
        tags: [
            {
                id: "63ed33eac79248a54ee04831",
                name: "greencloud",
                color: "#00ff80",
            },
        ],
    createdAt: "1676489715"
    },
]

Toggle Pause​

info

Use this endpoint to pause or unpause the execution of your function and all calls to it. This is useful if, for example, you want to want to pause your function while you make updates to it, or you have collected sample data for a specific time period and want to pause your function until your next data collection period. If you have created a public URL this will not be accessible while your function is paused, but will resume when you unpause your function.

Endpoint​

POST
https://api.greencloud.dev/v1/function/[functionId]/togglePause
https://api.greencloud.dev/v1/function/[functionId]/togglePause

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Example Request​

Empty body

Example Response​

Status: 204 No Content
Empty body

Delete​

info

Use this endpoint to delete a function from the GreenCloud system.

Endpoint​

DELETE
https://api.greencloud.dev/v1/function/[functionId]
https://api.greencloud.dev/v1/function/[functionId]

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Example Request​

Empty body

Example Response​

Status: 204 No Content
Empty body

Get Capabilities​

info

Use this endpoint to get capabilities of a function on the GreenCloud system.

Endpoint​

GET
https://api.greencloud.dev/v1/function/[functionId]/capabilities
https://api.greencloud.dev/v1/function/[functionId]/capabilities

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Example Request​

Empty body

Example Response​

Status: 200 OK
{
    "timeout": 10
    "cpuCount": 0,
    "memSize": 0,
    "networkLatency": 0,
    "privileged": true
}

Set Capabilities​

info

In GreenCloud, because of the disparate nature of the machines that will be connecting to the Dispatcher, we use something called Capabailities to be able to clearly utilise the best suited machine to the computational task that the function requires. This is the purpose of Capabilities. In setting the capabilities of a function you can restrict the machines that that function executes on. The purpose of this is to run on the most optimal machine for the function.

Endpoint​

POST
https://api.greencloud.dev/v1/function/[functionId]/capabilities
https://api.greencloud.dev/v1/function/[functionId]/capabilities

Request Headers​

KeyValueRequired
AuthorizationValid Access Tokentrue
Content-Typeapplication/jsontrue

Request Parameters​

ValueExampleRequired
function id63f47d24dab5eb85451f3b61true

Request Body​

KeyExampleRequirements
timeout10optional numeric gte=10 lte=120
cpuCount1optional numeric gte=0 lte=4
memSize1024optional numeric gte=0 lte=2048
privilagedtrueoptional bool

Example Request​

{
    "timeout": 10
    "cpuCount": 1,
    "memSize": 1024,
    "privileged": true
}

Example Response​

Status: 204 No Content
Empty body