Global Variable API

The Global Variable API provides endpoints for creating, retrieving, updating, and deleting global variables within your Nected workspace. Global variables are reusable data points or configuration settings that can be referenced across workflows and rules.

All Global Variable API endpoints require an authenticated request using the nected-api-key header. This key is specific to your workspace and must be kept secure.

Note: By default, the nected-api-key is set to private for security purposes. To retrieve your nected-api-key, follow these steps:

1. Log in to Nected.

2. Go to Authorization page from the left sidebar

3. View or regenerate your nected-api-key to use in API requests.

For easier testing and exploration, the Global Variable API endpoints are available in a Postman Collection.

---

Endpoints

1. Get All Global Variables

Retrieve a paginated list of all global variables in your workspace. This endpoint helps manage and review existing variables, including their values and data types.

Endpoint: GET /dev/variable/get

Method: GET

Description: Retrieves a list of all global variables in your workspace, with pagination support.

Request Parameters

• Headers:

  • nected-api-key (string, required) - Your API key to authenticate and link the request to your workspace. Learn how to get it here.

Example Request in cURL

curl --location 'https://api.nected.ai/dev/variable/get' \
--header 'nected-api-key: YOUR_API_KEY'

Response Parameters

• name (string) - Name of the global variable.

• dataType (string) - Data type of the variable (e.g., string, number).

• value (any) - The stored value of the global variable.

• checksum (string) - Unique checksum for data integrity verification.

Example Response

{
    "data": {
        "Pagination": {
            "perPage": 10,
            "totalPage": 1,
            "currentPage": 1,
            "totalRecord": 6
        },
        "data": [
            {
                "name": "jsonVal",
                "data_type": "json",
                "value": {
                    "key_name_1": "Dhanush",
                    "key_name_2": 1000000,
                    "key_name_3": true,
                    "key_name_4": "2024-07-17T10:57:35Z",
                    "key_name_5": [
                        "Snehasish"
                    ]
                },
                "checksum": "5f6fb9a21fe1c1daf9bf4ad0889f1abc"
            },
            {
                "name": "edtechLeadsBucketD",
                "data_type": "string",
                "value": "five",
                "checksum": "42fd91c999ac7c849639077c112b3dc7"
            },
            {
                "name": "edtechLeadsBucketC",
                "data_type": "string",
                "value": "9:30|10:30|11:20|12:20",
                "checksum": "0050c1883b30b5c863c6f82a56e937d7"
            },
            {
                "name": "edtechLeadsBucketB",
                "data_type": "string",
                "value": "5:30|6:30|7:20|8:20",
                "checksum": "11b1ca958bc63426285201909cd6ac36"
            },
            {
                "name": "edtechLeadsBucketA",
                "data_type": "string",
                "value": "1:20|2:40|3:30|4:10",
                "checksum": "60340af6799dfae8871019cb6150b755"
            },
            {
                "name": "base_price",
                "data_type": "numeric",
                "value": 12000,
                "checksum": "a0332d212b02f5671dcfefebe9e62deb"
            }
        ]
    },
    "code": "success",
    "message": "success."
}

Errors

• 401 Unauthorized: Missing or invalid nected-api-key.

  • Example: {"error": "Unauthorized access. Invalid API key."}

---

2. Get Single Global Variable

Retrieve details of a specific global variable by its name. This endpoint is useful for fetching the details of an individual variable.

Endpoint: GET /dev/variable/get/:name

Method: GET

Description: Fetches details of a specific global variable by name.

Request Parameters

• Headers:

  • nected-api-key (string, required) - Your API key to authenticate and link the request to your workspace.

• Path Parameters:

  • name (string, required) - Name of the global variable.

Example Request in cURL

curl --location 'https://api.nected.ai/dev/variable/get/testVariable' \
--header 'nected-api-key: YOUR_API_KEY'

Response Parameters

• name (string) - Name of the global variable.

• dataType (string) - Data type of the variable.

• value (any) - Stored value of the variable.

• checksum (string) - Checksum for data integrity verification.

Example Response

{
    "data": {
        "name": "asbc",
        "data_type": "boolean",
        "value": true,
        "checksum": "7b1f26d527356b66c9c364ceb7bebcb0"
    },
    "code": "success",
    "message": "success."
}

Errors

• 401 Unauthorized: Missing or invalid nected-api-key.

  • Example: {"error": "Unauthorized access. Invalid API key."}

• 404 Not Found: The specified variable does not exist in the workspace.

  • Example: {"error": "Global variable not found."}

---

3. Create Global Variable

Create a new global variable in your workspace with a specified name, dataType, and value. This endpoint is useful for adding configuration settings or data points.

Endpoint: POST /dev/variable/create

Method: POST

Description: Creates a new global variable with specified properties.

Request Parameters

• Headers:

  • nected-api-key (string, required) - Your API key to authenticate and link the request to your workspace.

• Body (JSON):

  • name (string, required) - Name of the global variable.

  • dataType (string, required) - Data type (e.g., string, number).

  • value (any, required) - Initial value of the global variable.

Example Request in cURL

curl --location 'https://api.nected.ai/dev/variable/create' \
--header 'nected-api-key: DycUp4vg1d56QdXm6cBSPrPUkTIHWH' \
--header 'Content-Type: application/json' \
--data '{
    "name":"testVariable",
    "dataType":"numeric",
    "value":1
}'

Response Parameters

• name (string) - The name of the created global variable.

• dataType (string) - Data type of the variable.

• value (any) - Initial value of the variable.

• checksum (string) - Unique checksum for data integrity verification.

Example Response

{
    "data": {
        "name": "testVariable",
        "data_type": "numeric",
        "value": 1,
        "checksum": "dcbd9130670e2f1b519a574ac1962b2b"
    },
    "code": "success",
    "message": "success."
}

Errors

• 401 Unauthorized: Missing or invalid nected-api-key.

  • Example: {"error": "Unauthorized access. Invalid API key."}

• 409 Conflict: A variable with the specified name already exists.

  • Example: {"error": "Global variable with this name already exists."}

---

4. Update Global Variable

Update the value of an existing global variable. This endpoint requires a valid checksum to ensure data integrity and avoid overwriting concurrent changes.

Endpoint: PATCH /dev/variable/update/:name

Method: PATCH

Description: Updates the value of an existing global variable by name.

Request Parameters

• Headers:

  • nected-api-key (string, required) - Your API key to authenticate and link the request to your workspace.

  • checksum (string, required) - Current checksum of the variable to prevent concurrent modification.

• Path Parameters:

  • name (string, required) - Name of the global variable to update.

• Body (JSON):

  • value (any, required) - New value for the global variable.

You can get the checksum of any variable from the response of the "Get All Global Variable", like this:

"name": "edtechLeadsBucketD",
        "data_type": "string",
        "value": "five",
        "checksum": "42fd91c999ac7c849639077c112b3dc7"

Example Request in cURL

curl --location --request PATCH 'https://api.nected.ai/dev/variable/update/testVariable' \
--header 'nected-api-key: YOUR_API_KEY' \
--header 'checksum;' \
--header 'Content-Type: application/json' \
--data '{
    "value":5
}'

Response Parameters

• name (string) - Name of the updated global variable.

• dataType (string) - Data type of the variable.

• value (any) - Updated value of the variable.

• checksum (string) - New checksum after the update.

Example Response

{
    "type": "object",
    "properties": {
        "data": {
            "type": "null"
        },
        "code": {
            "type": "string"
        },
        "message": {
            "type": "string"
        }
    }
}

Errors

• 401 Unauthorized: Missing or invalid nected-api-key.

  • Example: {"error": "Unauthorized access. Invalid API key."}

• 409 Conflict: Checksum mismatch due to concurrent modifications.

  • Example: {"error": "Checksum mismatch. Concurrent modification detected."}

---

5. Delete Global Variable

Delete a global variable by its name. This endpoint requires a valid checksum to ensure the request is intentional and to prevent accidental deletions.

Endpoint: DELETE /dev/variable/delete/:name

Method: DELETE

Description: Deletes a global variable by name if the correct checksum is provided.

Request Parameters

• Headers:

  • *`

nected-api-key`** (string, required) - Your API key to authenticate and link the request to your workspace.

• checksum (string, required) - Current checksum of the variable for validation.

• Path Parameters:

  • name (string, required) - Name of the global variable to delete.

Example Request in cURL

curl --location --request DELETE 'https://api.nected.ai/dev/variable/delete/testVariable' \
--header 'nected-api-key: YOUR_API_KEY' \
--header 'checksum;'

Response Parameters

• message (string) - Returns "ok" on successful deletion.

Example Response

{
    "data": true,
    "code": "success",
    "message": "success."
}

Errors

• 401 Unauthorized: Missing or invalid nected-api-key.

  • Example: {"error": "Unauthorized access. Invalid API key."}

• 409 Conflict: Checksum mismatch, indicating that the checksum provided does not match the current state of the variable.

  • Example: {"error": "Checksum mismatch. Concurrent modification detected."}

---

Error Responses

Common error responses include:

• 401 Unauthorized: Indicates that the nected-api-key is missing or invalid. Ensure that you are using the correct API key for your workspace.

  • Example Response:

    {
      "error": "Unauthorized access. Invalid API key."
    }
    

• 404 Not Found: This error occurs if the specified variable name does not exist in the workspace.

  • Example Response:

    {
      "error": "Global variable not found."
    }
    

• 409 Conflict: Checksum mismatch, which can occur if another user or process modified the variable before the request.

  • Example Response:

    {
      "error": "Checksum mismatch. Concurrent modification detected."
    }

---

This concludes the Global Variable API Documentation. These endpoints provide secure and comprehensive management of global variables within your Nected workspace, enabling flexible and reusable data handling across workflows and rules.