Backups API – Version 2
1 Introduction
The Backups API v2 lets you manage backups of the data in your app hosted in Mendix Cloud.
Data snapshots consist of a PostgreSQL database dump and all the file objects referenced from the database.
Database archives are a zip file which contains all the data in the snapshot, or the database and files separately if you prefer.
You cannot currently upload an archive through this API. This function is currently only supported via the Developer Portal. However, you can use this API to restore data from an existing environment snapshot.
This API focuses on working with snapshots and archives asynchronously, because these can be very long-running tasks for large quantities of data. It replaces the deprecated Backups API v1.
2 Authentication
The Backups API requires authentication via API keys that are bound to your Mendix account (for more information, see Deploy Authentication). In addition to the API Access permission, the Backups permission is also required to manage backups.
3 Examples
3.1 Downloading a Backup of Your Data
To download a backup of your data, do as follows:
-
Make sure that you have an API key and the API Access and Backups permissions.
-
If the snapshot already exists, find the snapshot ID.
-
If the snapshot does not exist, call
POST /api/v2/apps/<ProjectId>/environments/<EnvironmentId>/snapshots
to create a snapshot. For more information, see the Request Creation of an Environment Snapshot section below. -
Use the value of
snapshot_id
in the output to create an archive file from the snapshot. To do so, callPOST /api/v2/apps/<ProjectId>/environments/<EnvironmentId>/snapshots/<SnapshotId>/archives
. For more information, see the Request Creation of a Snapshot Archive section below. -
Use the value of
archive_id
in the output to check whether the creation of the archive is completed. To do so, callGET /api/v2/apps/<ProjectId>/environments/<EnvironmentId>/snapshots/<SnapshotId>/archives/<ArchiveId>
. For more information, see the Request Status of Creation of an Archive section below. -
After the archive is created, use the value of
url
in the output to download the backup archive.
4 API Calls
4.1 List Environment Snapshots
4.1.1 Description
Lists the snapshots of an environment. By setting the offset
parameter, you can page through the list of snapshots created for an environment.
|
|
4.1.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
Query Parameters
- offset (Long): Number of items to offset. Default is 0.
- limit (Long): Maximum number of items in response. Default is 100.
Example Request
|
|
4.1.3 Output
An object with the following key-value pairs:
- snapshots (List): List of snapshot objects.
- total (Long): The total number of snapshots for the requested environment.
- offset (Long): The offset value of the current request.
- limit (Long): The limit value of the current request.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
500 | SNAPSHOT_LISTING_FAILED | An error occurred while listing the backups. Please contact Support. |
Example Output
|
|
4.2 Request Creation of an Environment Snapshot
4.2.1 Description
Request the creation of a snapshot of an environment. The response is a JSON object containing the snapshot_id
attribute that identifies a snapshot. Use the snapshot_id
in an API request to check the progress of the creation of this snapshot.
|
|
4.2.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
Request Body
A JSON object with the following attributes:
- comment (String): Optional comment for this snapshot.
Example Request
|
|
4.2.3 Output
A JSON object with the following key-value pairs:
- snapshot_id (String): Unique identification of the snapshot job.
- status_message (String): Human readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
followed byrunning
and eventually reaches eitherfailed
orcompleted
end states. - model_version (String): Model version that was running when the snapshot was created.
- expires_at (String): ISO 8601 date and time when this snapshot will be expired.
- comment (String): A comment describing this snapshot. Can be set by users for easier future reference.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
400 | ENVIRONMENT_BUSY | Environment is busy, please try again later or contact Support for assistance. |
400 | INVALID_STATE | Failed to create a backup. There is currently a maintenance action in progress. Please wait until that is finished. |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
404 | NOT_FOUND | Snapshot not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
|
|
4.3 Request Status of Creation of a Snapshot
4.3.1 Description
Check the current status of an ongoing snapshot creation.
|
|
4.3.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- SnapshotId (String): Identifier of the snapshot being created.
Example Request
|
|
4.3.3 Output
An object with the following key-value pairs:
- snapshot_id (String): Unique identification of the snapshot job.
- status_message (String): Human readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches afailed
orcompleted
end state. - model_version (String): Model version that was running when the snapshot was created.
- expires_at (String): ISO 8601 date and time when this snapshot will be expired.
- comment (String): A comment describing this snapshot. Can be set by users for easier future reference.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
404 | NOT_FOUND | Snapshot not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
|
|
4.4 Request Creation of a Snapshot Archive
4.4.1 Description
Requests the creation of an archive of a backup snapshot. The response is a JSON object containing the archive_id
attribute which identifies an archive. use this archive_id
in an API request to check the progress of the creation of this archive, and obtain a URL to allow you to download it.
|
|
4.4.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- SnapshotId (String): Identifier of the snapshot for which you want to create an archive.
Query Parameters
- data_type (String): The type of data to retrieve. Valid types are: database_only and files_and_database. Default value is files_and_database.
Example Request
|
|
4.4.3 Output
An object with the following key-value pairs:
- archive_id (String): Unique identification of the archive job.
- status_message (String): Human readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches either afailed
orcompleted
end state. - data_type (String): Type of data of the requested archive.
- snapshot_id (String): Snapshot identifier of which this archive belongs to.
- url (String): Direct URL to the backup archive. This URL can be used with download managers.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
400 | UNSUPPORTED | Unsupported data_type |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
404 | NOT_FOUND | Snapshot not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
|
|
4.5 Request Status of Creation of an Archive
4.5.1 Description
After a request to create an archive is submitted, you can check the progress of the archive creation using the archive_id
. The archive creation will eventually reach one of the following end states: completed or failed. When it is completed, the url
attribute is populated with a direct link to your requested backup. This link is valid for eight hours after completion.
|
|
4.5.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- SnapshotId (String): Identifier of the backup.
- ArchiveId (String): Identifier of the archive being created.
Example Request
|
|
4.5.3 Output
An object with the following key-value pairs:
- archive_id (String): Unique identification of the archive job.
- status_message (String): Human readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches either afailed
orcompleted
end state. - data_type (String): Type of data of the requested archive.
- snapshot_id (String): Snapshot identifier of which this archive belongs to.
- url (String): Direct URL to the backup archive. This URL can be used to download your backup archive file.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
404 | NOT_FOUND | Snapshot not found. |
404 | NOT_FOUND | Archive not found. |
Example Output
|
|
4.6 Update an Existing Snapshot
4.6.1 Description
Set a new comment for an existing snapshot. The updated_at attribute remains unchanged after this operation.
|
|
4.6.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- SnapshotId (String): Identifier of the backup.
- Comment (String): Optional comment for this snapshot.
Request Body
A JSON object with the following attributes:
- comment (String): New comment for this snapshot.
Example Request
|
|
4.6.3 Output
An object with the following key-value pairs:
- snapshot_id (String): Unique identification of the snapshot job.
- status_message (String): Human-readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches either afailed
orcompleted
end state. - model_version (String): Model version that was running when the snapshot was created.
- expires_at (String): ISO 8601 date and time when this snapshot will be expired.
- comment (String): A comment describing this snapshot. Can be set by users for easier future reference.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
404 | NOT_FOUND | Snapshot not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
|
|
4.7 Delete an Existing Snapshot
4.7.1 Description
Delete an existing snapshot.
|
|
4.7.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- SnapshotId (String): Identifier of the backup.
- Comment (String): Optional comment for this snapshot.
Example Request
|
|
4.7.3 Output
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
No content is returned when a backup has been successfully removed.
4.8 Request a Restore of a Snapshot to an Environment
4.8.1 Description
Restore a previously created backup snapshot to an environment. The environment to which the data will be restored must be stopped before using this call. The response of a successful call contains the details of the request. This call is only available for Mendix Cloud applications. Please note that the source_snapshot_id
can be a snapshot created for a different environment, similar to the “restore into” functionality in the Developer Portal.
|
|
4.8.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
Query Parameters
-
source_snapshot_id (String): Identifier of the snapshot that will be restored. This value is required; it must belong to a snapshot within the same application, although it could be a different environment.
-
db_only (Boolean): Boolean flag. Set this to true if you are doing a database-only restore operation. It defaults to false if not present.
Settingdb_only
totrue
will not restore any of your files, leading to a risk that data will be missing from your app or that your app will not work as expected. Use this option with caution.
Example Request
|
|
|
|
4.8.3 Output
An object with the following key-value pairs:
- restore_id (String): Unique identification of the restore job.
- status_message (String): Human readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches either afailed
orcompleted
end state. - source_snapshot_id (String): Identifier of the snapshot being restored.
- source_environment_id (String): Identifier of the environment from which the source snapshot was created.
- target_environment_id (String): Identifier of the target environment to which the snapshot is being restored.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
400 | NOT_FOUND | Source snapshot not found |
400 | INVALID_STATE | Failed to restore a backup. There is currently a maintenance action in progress. Please wait until that is finished. |
400 | ERROR_NOT_ALLOWED | Not allowed to restore backups. |
400 | ERROR_NOT_ALLOWED | Restore failed, backup is not in the right state to start restoring. |
400 | ERROR_NOT_ALLOWED | Please stop loft before restarting a backup. |
400 | ENVIRONMENT_BUSY | Environment is busy, please try again later or contact Support for assistance. |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
500 | SERVICE_UNAVAILABLE | Operation failed. Please try again later or contact Support if the problem persists. |
Example Output
|
|
4.9 Request Status of a Snapshot Restore
4.9.1 Description
Check the status of a restore request.
|
|
4.9.2 Request
Request Parameters
- ProjectId (String): Unique project identifier. Can be looked up via the Developer Portal or apps API.
- EnvironmentId (String): Unique environment identifier. Can be looked up via the Developer Portal or environments API.
- RestoreId (String): Identifier of the request to restore the data.
Example Request
|
|
4.9.3 Output
An object with the following key-value pairs:
- restore_id (String): Unique identification of the restore job.
- status_message (String): Human0readable status message of this job.
- finished_at (String): ISO 8601 date and time when this job reached the end state.
- updated_at (String): ISO 8601 date and time when this job was updated.
- created_at (String): ISO 8601 date and time when this job was created.
- state (String): Current state of this job. It always starts with
queued
, followed byrunning
, and eventually reaches either afailed
orcompleted
end state. - source_snapshot_id (String): Identifier of the snapshot being restored.
- source_environment_id (String): Identifier of the environment from which the source snapshot was created.
- target_environment_id (String): Identifier of the target environment to which the snapshot is being restored.
Error Codes
HTTP Status | Error code | Description |
---|---|---|
400 | INVALID_PARAMETERS | Not enough parameters given. Please set project_id and environment_id parameters. |
400 | NOT_SUPPORTED | This endpoint can only be used with Mendix Cloud |
400 | NOT_FOUND | Restore not found |
403 | NO_ACCESS | The user does not have access to the backups of this environment. |
404 | ENVIRONMENT_NOT_FOUND | Environment not found. |
Example Output
|
|
Feedback
Was this page helpful?
Glad to hear it! Thank you for your response.
Sorry to hear that. Please tell us how we can improve.