Skip to main content

Overview

Contributors

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

Note 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

POST

Create an object instance

GET

Retrieve an object instance or collection

PATCH

Update an existing object

DELETE

Remove an existing object

Request headers

Request Header Description

Authorization

Required. Contains a JWT access token

x-agent-id

Required. Contains the BlueXP Connector ID.

x-netapp-cache-control

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

200

OK:Returned for successful operation completion

400

Bad Request:Returned if the input is malformed and could not be parsed

401

Unauthorized:Returned if user authentication failed or the token has expired

403

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   "{&quotgrant_type&quot: &quotrefresh_token&quot, &quotrefresh_token&quot: &quotJxaVHn9cGkX92aPVCkhat3zxxxxxwsC9qMl_pLHkZtsVA&quot, &quotclient_id&quot: &quotMu0V1ywgYteI6w1MbD15fKfVIUrNXGWC&quot} "

Obtain your NetApp Cloud Central account ID

  curl -X GET  "https://cloudmanager.cloud.netapp.com/tenancy/account"    -H "accept: application/json"  -H "&quotauthority: cloudmanager.cloud.netapp.com&quot" -H "&quotaccept-language: en-GB,en;q=0.9&quot"  -H "&quotauthorization: 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 "&quotauthority: api.services.cloud.netapp.com&quot" -H "&quotaccept-language: en-GB,en;q=0.9&quot"  -H "&quotauthorization: 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 "&quotx-agent-id: iZwFFeVCZjWnzGlw8RgD0QQNANZvpP7Iclients&quot"  -H "&quotauthorization: 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"}}"