With the mabl DataTable API, you can programmatically manage DataTables and their individual scenarios. The endpoints available in mabl's DataTable API include:
Some use cases for the DataTable API include:
- Making bulk updates to large DataTables
- Writing a script that automates changes to DataTables
- Updating DataTables without having to navigate to the DataTables page
Getting started
Authentication
To authenticate your requests, follow authentication steps outlined in the Intro to the mabl API guide.
Mabl resource IDs
The DataTable API uses the following mabl resource IDs as parameter values:
- Workspace ID
- DataTable ID
- Scenario ID
To retrieve a specific workspace ID or DataTable ID, see our guide on mabl resource IDs.
To retrieve a specific scenario ID, use the DataTable API or the mabl CLI:
- DataTable API: Use the Get Scenarios endpoint
- mabl CLI: use the
mabl datatables describecommand
DataTable endpoints
With the DataTable endpoints, you can programmatically create, query, get, update, and remove DataTables.
Retrieve DataTables for a given workspace:
- GET
/dataTables?workspace_id={workspace_id}
By default, this endpoint retrieves all DataTables for the workspace, but you may set a maximum number of DataTables to return in a single response with the limit parameter. Additional pages of results can be retrieved by passing the cursor parameter on a subsequent call.
Create a new DataTable:
- POST
/dataTables
In the request body, provide a JSON object with the workspace ID, DataTable name, scenarios, variables, and values. For example, the following request body creates a DataTable called "New Users" with the variables "name", "email", and "phone":
{
"workspace_id": <Enter your workspace ID in quotes>,
"data_table": {
"name": "New Users"
},
"scenarios": [
{
"name": "Mike",
"variables": [
{
"name": "name",
"value": "Mike Richardson"
},
{
"name": "email",
"value": "[email protected]"
},
{
"name": "phone",
"value": "009555114343"
}
]
},
{
"name": "Steve",
"variables": [
{
"name": "name",
"value": "Steven King"
},
{
"name": "email",
"value": "[email protected]"
},
{
"name": "phone",
"value": "004555554235432"
}
]
}
]
}
Maximum number of scenarios
The maximum number of scenarios for a DataTable is 500.
Retrieve metadata about a specific DataTable:
- GET
/dataTables/{datatable_id}
Update the DataTable name:
- PUT
/dataTables/{datatable_id}
In the request body, provide a JSON object with the name that you want to update the DataTable to. For example, the following request body updates the DataTable name to "Existing users."
{
"name": "Existing users",
}
Note
When a plan is triggered, mabl pulls the most recent version of the DataTable for tests associated with DataTables.
If an update is made to a DataTable in a plan run, subsequent tests in the plan that are associated with the DataTable will not use the updated scenario values until after the plan has finished.
Variable endpoints
With the variable endpoints, you can programmatically create, query, update, and remove variable names for a DataTable.
Retrieve the current variable names for a DataTable:
GET /dataTables/{datatable_id}/variableNames
Create and add a new variable to the DataTable. Provide a default value for the existing scenarios:
- POST
/dataTables/{datatable_id}/variableNames
Provide a default value for the existing scenarios in the request body. For example, to add a new DataTable variable named location with a value of New York, format the request body as follows:
{
"name": "location",
"default_value": "New York"
}
Update a DataTable variable name:
- PATCH
/dataTables/{datatable_id}/variableNames
In the request body, provide a JSON object with the variable name to update as the value of "name" and the new variable name as the value of "new_name". For example, the following request body updates the variable name location to city.
{
"name": "location",
"new_name": "city"
}
Remove a variable name and its associated values from a DataTable.
- POST
/dataTables/{datatable_id}/variableNames/removeVariableName
In the request body, provide a JSON object with the variable that you want to delete. For example, the following request body deletes the variable city from the DataTable.
{
"name": "city",
}
Scenario endpoints
With the scenario endpoints, you can programmatically create, query, get, update, and remove individual scenarios in a DataTable.
Retrieve scenarios, variable values, and scenario IDs associated with a DataTable:
- GET
/dataTables/scenarios?datatable_id={data_table_id}
Create and add a new scenario to the DataTable:
- POST
/dataTables/{datatable_id}/scenarios
In the request body, provide a JSON object with the new scenario name and the values for each variable. For example, the following request body adds the scenario Jane to the "New users" DataTable with values for three variables: full_name, email, and phone.
{"name": "Jane",
"variables": [
{
"name": "name",
"value": "Jane Doe"
},
{
"name": "email",
"value": "[email protected]"
},
{
"name": "phone",
"value": "(999) 555-1111"
},
]
}
Retrieve the variable values associated with a specific scenario:
- GET
/dataTables/scenarios/{scenario_id}
Update variable values for a specific scenario:
- PUT
/dataTables/scenarios/{scenario_id}
In the request body, provide a JSON object with the scenario name and updated values for each variable. This sample request body updates the email address for the Jane scenario in the "New users" DataTable:
{"name": "Jane",
"variables": [
{
"name": "name",
"value": "Jane Doe"
},
{
"name": "email",
"value": "[email protected]"
},
{
"name": "phone",
"value": "(999) 555-1111"
},
]
}
Delete a specific scenario using its scenario ID.
- DELETE
/dataTables/scenarios/{scenario_id}