Overview
BlueXP backup and recovery is a BlueXP service that provides backup and restore capabilities for protection and long-term archiving of your data residing in Cloud Volumes ONTAP and on-premises ONTAP clusters (AFF/FAS/OTS). By using this service, you can automatically generate and store backups in an object store in the public or private cloud account of your choice, and you can easily restore data any time and to any location as per your requirements.
There are ten categories of endpoints defined within BlueXP BlueXP backup and recovery.
-
Backup
-
Catalog
-
Cloud
-
Job
-
License
-
Ransomware scan
-
Restore
-
Single file-level restore (SFR)
-
StorageGRID (sg)
-
Working environment
Before using the API reference documentation, review the Get started section for the BlueXP APIs. For more information about the security tokens and identifiers you'll need when using the API, review the Common workflows and tasks section. |
REST implementation
HTTP methods
Method | Description |
---|---|
|
Create an object instance |
|
Retrieve an object instance or collection |
|
Update an existing object |
|
Remove an existing object |
Request headers
Request Header | Description |
---|---|
|
Required. Contains a JWT access token |
|
Required. Contains the BlueXP Connector ID. |
|
This header bypasses the local cache and retrieves actual data from upstream sources like a BlueXP SaaS application and ONTAP clusters. |
Query parameters
You can use query parameters with endpoints in the following components:
Component | Query Parameter |
---|---|
sfr |
accountId(required),volumeId,snapshotId. |
backup |
accountId(required),workingEnvironmentId,volumeId,snapshotId. |
restore |
accountId(required). |
Working environment |
accountId(required),workingEnvironmentId,volumeId,snapshotId. |
cloud |
accountId(required),workingEnvironmentId,volumeId,snapshotId,awsAccountId,regionCode,subscriptionId,vaultName,projectId,jobId. |
license |
accountId(required),workingEnvironmentId. |
catalog |
accountId(required),workingEnvironmentId. |
job |
accountId(required),jobId. |
Response headers
This API uses the standard HTTP response headers common with all BlueXP APIs. See REST implementation for more information.
HTTP status codes
HTTP Status Code | Description |
---|---|
|
OK:Returned for successful operation completion |
|
Bad Request:Returned if the input is malformed and could not be parsed |
|
Unauthorized:Returned if user authentication failed or the token has expired |
|
Forbidden:Returned for authorization errors depending on the resource and token |
Error handling
There are two processes involved with error handling and processing.
-
The error is logged for supportability
-
The error is also returned to the caller for any specifichandling
cURL examples
Retrieve specific volume details
This example retrieves the details of a specific volume that has been backed up by using BlueXP BlueXP backup and recovery.
curl -X GET "https://cloudmanager.cloud.netapp.com/account/(account_id)/providers/cloudmanager_cbs/api/v1/backup/working-environment/(working_environment_id)/volume/(volume_id)" -H "accept: application/json" -H "authorization: (user token)"
Frequently asked questions
There are multiple versions of the same command. Which version should I use?
If there are multiple versions of the same API endpoint, make sure to use the latest version of the API. The version of each endpoint is mentioned in the path.
What's the difference between a user token and service token and why do we need two types of token authorization ?
A user token is used for communication between a user (or the UI) and the BlueXP REST APIs, whereas the service token is used for communication between two services (machine-to-machine interaction) in BlueXP. The type of token required to invoke an API is documented in the description of each endpoint.
What is difference between SFR BlueXP backup and recovery APIs and Catalog BlueXP backup and recovery APIs?
The SFR BlueXP backup and recovery APIs provide the option to use the "Browse and Restore" feature while performing a volume level or single/multiple file restore operation from backups stored on the cloud.The Catalog BlueXP backup and recovery APIs have introduced a new "Search and Restore" feature, which enables you to search for a specific file from all backups stored on Amazon S3 cloud storage and then perform a restore operation. It enables you to perform a quick and focused search for files across all the backups in the cloud and gives you the option to narrow down the searches by using multiple search criteria.
Why has the export file system API endpoint under the SFR category been deprecated?
Previously, BlueXP backup and recovery relied on an additional Cloud Restore VM instance for exporting the Snapshot copies and creating a file list when you initiated a "File Restore" operation from the Restore dashboard. Now instead of creating an additional cloud restore virtual machine (VM) instance during a file-level restore operation, BlueXP backup and recovery deploys a restore container on the Connector VM instance. These containers contain the latest Active Data Connector image(version 1.4). This implementation doesnt require the file system to be exported, therefore the export file system API endpoint under the SFR category has been deprecated.
Why have the API endpoints under the jobs category changed?
The old job API endpoints have been replaced with a set of new job API endpoints. The functionality of the new endpoints differ from the old ones. Previously, the job endpoints were used to retrieve a list of jobs and the details of a particular job. The new job API endpoints allow services to create job entries, update the status of a job directly in the database, and retrieve the current status of a job from the database.
How to use BlueXP backup and recovery REST APIs
Getting started
To get started with the BlueXP backup and recovery APIs, you need to obtain a user token, a Cloud Central account ID, and the Cloud Connector ID. When making API calls, add the user token in the Authorization header and the Cloud Connector ID in the x-agent-id header. Use the Cloud Central account ID in the APIs.
Obtain a user token from NetApp Cloud Central.
Make sure to generate the refresh token from the following link: https://services.cloud.netapp.com/refresh-token/. The refresh token is an alpha-numeric string that is used to generate a user token.
curl -X GET "https://netapp-cloud-account.auth0.com/oauth/token?=" -H "Content-Type: application/json" -d "{"grant_type": "refresh_token", "refresh_token": "JxaVHn9cGkX92aPVCkhat3zxxxxxwsC9qMl_pLHkZtsVA", "client_id": "Mu0V1ywgYteI6w1MbD15fKfVIUrNXGWC"} "
Obtain your NetApp Cloud Central account ID
curl -X GET "https://cloudmanager.cloud.netapp.com/tenancy/account" -H "accept: application/json" -H ""authority: cloudmanager.cloud.netapp.com"" -H ""accept-language: en-GB,en;q=0.9"" -H ""authorization: Bearer eyJhbGciOiJSUzI1NiIsInR……"
This API will return a response like the following. You can retrieve the account ID by parsing the output from [0].[ accountPublicId].
Response:
"[{"accountPublicId":"account-i6vJXvZW","accountName":"rashidn","isSaas":true,"isGov":false,"isPrivatePreviewEnabled":false,"is3rdPartyServicesEnabled":false,"accountSerial":"96064469711530003565","userRole":"Role-1"}………"
Obtain the x-agent-id that contains the BlueXP Connector ID.
curl -X GET "https://api.services.cloud.netapp.com/occm/list-occms/account-OOnAR4ZS?excludeStandalone=true&source=saas" -H "accept: application/json" -H ""authority: api.services.cloud.netapp.com"" -H ""accept-language: en-GB,en;q=0.9"" -H ""authorization: Bearer eyJhbGciOiJSUzI1NiIsInR……"
This API will return a response like the following. You can retrieve the agent ID by parsing the output from occm.[0].[agent].[agentId].
Response:
"{"occms":[{"account":"account-OOnAR4ZS","accountName":"cbs","occm":"imEdsEW4HyYTFbt8ZcNKTKDF05jMIe6Z","agentId":"imEdsEW4HyYTFbt8ZcNKTKDF05jMIe6Z","status":"ready","occmName":"cbsgcpdevcntsg-asia","primaryCallbackUri":"","manualOverrideUris":[],"automaticCallbackUris":[],"createDate":"1652120369286","agent":{"useDockerInfra":true,"network":"default","name":"cbsgcpdevcntsg-asia","agentId":"imEdsEW4HyYTFbt8ZcNKTKDF05jMIe6Zclients","provider":"gcp","systemId":"a3aa3578-bfee-4d16-9e10-"
Example using the APIs
The following example shows an API call to activate a backup on a working environment with a new policy that has daily, hourly, and weekly labels set, and archive after days set as 180 days in East-US-2 region in Azure cloud. This enables backup only on a working environment when no volumes are backed up. If you choose "`"auto-backup-enabled": true, then any existing volume in the system are backed up and future volumes are added.
curl -X GET "https://cloudmanager.cloud.netapp.com/account/account-DpTFcxN3/providers/cloudmanager_cbs/api/v3/backup/working-environment/VsaWorkingEnvironment-99hPYEgk" -H "accept: application/json" -H ""x-agent-id: iZwFFeVCZjWnzGlw8RgD0QQNANZvpP7Iclients"" -H ""authorization: Bearer eyJhbGciOiJSUzI1NiIsInR……" -d "{"provider":"AZURE","backup-policy": {"archive-after-days": 180,"rule": [{"label": "hourly","retention": "2"},{"label": "daily","retention": "30"},{"label": "weekly", "retention": "52"}]},"ip-space": "Default","region": "eastus2","azure": {"resource-group": "rn-test-backup-rg", "subscription": "3beb4dd0-25d4-464f-9bb0-303d7cf5c0c2"}}"