Project Variables API🔗

The Project Variables API provides two sets of endpoints for managing project variables and environment-level overrides for each project variable.

Get Project Variables🔗

This endpoint allows you to list project variables for a given account and project. As a pageable endpoint within the Data Productivity Cloud, results are paged through by appending the page information as query parameters in the request URL.

The paging parameters are as follows:

Parameter	Purpose	Default value	Example value
page	Which page to fetch	0	2
size	How large each page of results should be	25	10

These would be appended to the URL as query parameters, for example:

Paged Request URL: GET /v1/projects/{projectId}/variables?page=2&size=10

If no paging information is provided, the defaults listed above will be used instead.

Example request🔗

Base URL: GET /v1/projects/{projectId}/variables

Example success response:

HTTP 200 OK
{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "test-variable-1",
      "type": "TEXT",
      "behaviour": "SHARED",
      "description": "A test text variable",
      "value": "test-value-1",
      "supportsDoubleResolution": false
    },
    {
      "id": "7d350099-17c1-42d6-9035-0bd92c68ebb0",
      "name": "test-variable-2",
      "type": "NUMBER",
      "behaviour": "COPIED",
      "description": "A test number variable",
      "value": 42,
      "supportsDoubleResolution": true
    }
  ],
  "page": 0,
  "size": 2,
  "total": 2
}

Create Project Variable🔗

This endpoint allows you to create a new project variable for a given account and project.

Example request🔗

Base URL: POST /v1/projects/{projectId}/variables

Example request body:

{
  "name": "test_create_variable",
  "type": "TEXT",
  "behaviour": "SHARED",
  "description": "A new test variable created via API",
  "value": "variable-value",
  "supportsDoubleResolution": false
}

Example success response:

HTTP 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "test_create_variable",
  "value": "variable-value"
}

Update Project Variable🔗

This endpoint allows you to perform a partial update to an existing project variable, identified by the immutable variable name.

Currently, type and behaviour are required parameters of the request, even if the values are to remain unchanged.

Example request🔗

Base URL: PATCH /v1/projects/{projectId}/variables/{variableName}

Example request body:

{
  "type": "TEXT",
  "behaviour": "SHARED",
  "description": "An updated description of a test variable created via API",
  "value": "variable-value-updated",
  "supportsDoubleResolution": false
}

Example success response:

HTTP 204 No Content

{}

Delete Project Variable🔗

This endpoint allows you to delete a variable by name, along with all environment-level overrides for the variable.

Example request🔗

Base URL: DELETE /v1/projects/{projectId}/variables/{variableName}

Example success response:

HTTP 204 No Content

{}

Get Project Variable Environment Overrides🔗

This endpoint allows you to retrieve a variable along with any associated environment-level overrides. You can choose to provide an environment name to return a single override.

Example request without a specified environment🔗

Base URL: GET /v1/projects/{projectId}/variables/{variableName}/environment-overrides

Example success response:

HTTP 200 OK
{
  "variable": {
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "test_variable",
    "type": "TEXT"
  },
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "staging",
      "value": "staging-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ]
}

Example request with a specified environment🔗

Base URL: GET /v1/projects/{projectId}/variables/{variableName}/environment-overrides?environmentName=dev

Example success response:

HTTP 200 OK
{
  "variable": {
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "test_variable",
    "type": "TEXT"
  },
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    }
  ]
}

Create Project Variable Environment Overrides🔗

This endpoint allows you to create new environment-level overrides for an existing project variable, or to update existing overrides.

If you specify an environment that doesn't already have an override for the specified project variable, this will create a new environment-level override for that project variable. If you specify an environment that does already have an override for the specified project variable, the override will be updated.

If any environment overrides are unable to be created, an entry will be included in the failedOverride portion of the response.

Common error scenarios include:

The environment does not exist.
You do not have permission to create or edit environment overrides.
The provided value for the override does not have a compatible type for the variable (for example, providing a number as an override for a text variable).

Example request🔗

Base URL: POST /v1/projects/{projectId}/variables/{variableName}/environment-overrides

Example request:

{
  "overrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ]
}

Example success response:

HTTP 200 OK
{
  "variableName": "test_variable",
  "type": "TEXT",
  "successfulOverrides": [
    {
      "environmentName": "dev",
      "value": "dev-override-value"
    },
    {
      "environmentName": "prod",
      "value": "prod-override-value"
    }
  ],
  "failedOverrides": []
}

Delete Project Variable Environment Override🔗

This endpoint allows you to remove a specific environment-level override from an existing project variable, specified by environment name.

Example request🔗

Base URL: DELETE /v1/projects/{projectId}/variables/{variableName}/environment-overrides/{environmentName}

Example success response:

HTTP 204 No Content

{}