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:
Log in to Nected.
Go to Authorization page from the left sidebar
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
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
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
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
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
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
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:
Example Request in cURL
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
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
Response Parameters
message (string) - Returns "ok" on successful deletion.
Example Response
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:
404 Not Found: This error occurs if the specified variable name does not exist in the workspace.
Example Response:
409 Conflict: Checksum mismatch, which can occur if another user or process modified the variable before the request.
Example Response:
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.
Last updated