Restful API examples for 3.0.x

Restful API examples for 3.0.x

Background

The purpose of this article is to help you get started with N2WS Restful API for 3.0.x and provide you some examples on how to use it.
However it is not meant to replace the official documentation - for full and accurate information on all the APIs and possible parameters, please check our official guide:
  1. RESTful API 1.4 Guide for 3.0.x

How To enable REST API and obtain token Examples (cURL)

General info:
in order to use N2WS Restful API you first need to enable it via the UI console.
When you enable it in the UI Console, you will get an Authentication Key which is used to obtain access & refresh tokens.

The Access Token is used in all followup API calls and is valid for 1 hours by default.
The Refresh Token is valid for 24 hours by default and can be used to generate new access tokens.
You can read more about this in Chapter 1. "Overview" of our RESTful API 1.4 Guide for 3.0.x

Step by Step example:
1. Connect with your user to the UI Console (Admin user in this case) and click on 'Settings'


2. Enable the API and generate a Key:


Now you have the Key which you can use to generate Access & Refresh tokens.
For the next steps we used CURL Command in Ubuntu OS.

3. Obtain tokens
API_KEY='1f020e8ce04bd378a7705d4b91fcdcdef50324b3ba4eee915622f7e25d15ba1d9430d793c4aebe6e711034f51202f56389de4bf6a2569c96'
obtain token API:
curl -k -X POST https://$HOST/api/token/obtain/api_key/ -H 'Accept: application/json; version=1.4.0' -H 'Content-Type: application/json' -d '{"api_key": "'"$API_KEY"'"}' | jq

Results:

note: the jq module i used above is just to make the json output more readable in the Linux terminal, it is optional.

i will also save the tokens into variables to be used later

Now that we have the access token, we can start using the various APIs available.
But if an hour have passed and the access token expired, you can use the refresh API & Token to generate a new access token
curl -k -X POST https://$HOST/api/token/refresh/ -H 'Accept: application/json; version=1.4.0' -H 'Content-Type: application/json' -d '{"refresh": "'"$REFRESH_TOKEN"'"}' | jq

Result:


We will update the var with the new value

Various Rest API Examples (cURL)

General info:
in this section we'll show a few CURL API commands examples, but there are many more options in the user guide.
And for every example shown here, there are many more possible parameters in the user guide.

Examples:
1.
We can use the the following CURL command to list all the backup records:
curl -k -X GET https://$HOST/api/backups/ -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

We can also add a query parameter, for example below we have added '?status=B ' to the same command, this now will only list successful backups
curl -k -X GET https://$HOST/api/backups/?status=B -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

The output will look like this:


This is similar to going to the backup monitor in the UI Console and filtering only successful backup records.


In addition similar to ordering in the UI Console, we can also do it for the results in the Rest Command.
For the command below i added &ordering=-start_time, this tells it to order by start_time and the minus sign tell it to order descending, we also wrapped the URL with ""
curl -k -X GET "https://$HOST/api/backups/?status=B&ordering=-start_time" -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

2.
Now, Let's say we want to run the "test" policy ASAP, similar to what is available in the UI:


First i need to find the relevant policy ID with the list policy API, below command will list the policies
curl -k -X GET "https://$HOST/api/policies/?search=test" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
You probably noticed the query param ?search=test, what it does is look for the search term in the fields: name, description, name of related schedule, description of related schedule

result: list of policies, one of them is the one we need.


now we can run the ASAP API
POLICY_ID='2'
curl -k -X POST "https://$HOST/api/policies/${POLICY_ID}/backups/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

The output of this API will give you a tracker_id for checking the backup:


With this ID we can call again the list backup records API
curl -k -X GET https://$HOST/api/backups/?tracker_id=1 -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq


Additional Examples:
1. List schedule:
curl -k -X GET "https://$HOST/api/schedules/?ordering=every_unit,every_how_many" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

2. List accounts
curl -k -X GET "https://$HOST/api/accounts/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

3. List backup accounts
curl -k -X GET "https://$HOST/api/accounts/backup/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

4. List snapshots
BACKUP_ID='60'
curl -k -X GET "https://$HOST/api/backups/${BACKUP_ID}/snapshots/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

5. List S3 repositories
curl -k -X GET https://$HOST/api/s3_repositories/ -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

6. Create policy
ACCOUNT_ID=1
POLICY_NAME='fromCURL'
curl -k -X POST "https://$HOST/api/policies/" -H "Accept: application/json;" -H 'Content-Type: application/json' -H "Authorization: Bearer ${ACCESS_TOKEN}" -d '{"account": "'"$ACCOUNT_ID"'", "name": "'"$POLICY_NAME"'"}' | jq

7. Recover volume to Linux in DR Account
BACKUP_ID=822 - retrieved with curl -k -X GET https://$HOST/api/backups/?status=B -H 'Accept: application/json; version=1.4.0' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq
VOLUME_ID=96retrieved with curl -k -X GET "https://$HOST/api/backups/822/snapshots/volumes/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq 
Account_ID=7 retrieved with curl -k -X GET "https://$HOST/api/accounts/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

curl -k -X POST "https://$HOST/api/backups/822/snapshots/volumes/96/recover/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" -H "Content-Type: application/json" -d '{ "attach_behaviour": "attach_free", "attach_to": "i-096510bc82f0a98b9", "device": "/dev/sdy", "zone": "us-east-1b", "preserve_tags": "False", "to_account": "7"}'| jq

8. get snapshot report
curl -OJ -k -X GET "https://$HOST/api/reports/snapshots/?from_time=2020-08-12T00:00:00Z&to_time=2020-08-13T23:59:59Z" -H "Accept: text/csv;" -H "Authorization: Bearer ${ACCESS_TOKEN}" 
  1. Note: the server will take the timezone into account, so if server is set to -04:00 timezone it will reduce 4 hours from the provided time.

What examples are available in the official guide? (cURL & Python)

In addition to all of the above examples, you also have the following examples available in our RESTful API 1.4 Guide for 3.0.x

CURL Examples by Chapter:
  1. 2.1.1. Create a CPM Schedule
  2. 2.1.2. Update a CPM Schedule
  3. 2.1.3. List CPM Schedules
  4. 2.1.4. Delete a CPM Schedule
  5. 2.2.1. Download Support Logs
  6. 2.2.2. Download Cleanup Logs
  7. 2.3.1. Download Snapshots Report
  8. 2.3.2. Download Backups Report 
Python Examples by Chapter:
  1. 2.4. Python Script - Obtain token, refresh token and get user list

Appendix A: Obtain Token & List Polcies screenshots (Postman)

In addition to the above you can also use other methods to call the rest API, for example Postman application.

I'll show here few screenshots on how to create a request for N2WS RestAPI in postman,
However for information about RestAPI, read the above KB Article and the RESTful API 1.4 Guide for 3.0.x.

General:
Each method below is a separate request in postman:


In addition, you can create environment parameter to simplify calls to the API,
For example host parameter which will be used by all API calls.


Obtain token method in Postman:
For obtain token you need this parameters:


Request details: 


Headers:

Body will contain reference to the api_key environment parameter
the environment parameter will hold the API key from the CPM

Note: When you see a string wrapped with {{ }}, this means postman will take the value from the environment parameters

Once the API return the token, You can add the returned access token to the environment details for easy access by other API that need it.


List policies method in Postman:


Request details:
I have added account=1 to the list policies to filter by account ID=1,
but you can add any other parameter or no parameters.


Authorization contain the reference to the environment parameter that contains the token we got from the obtain token call.


Header contain this


Appendix B: Create/List/Delete screenshots (Python)

In addition to cURL & Postman, you can also use python to call the rest API,
I'll show here few screenshots on how to call policies RestAPI's via python.

This is just a snippet of a code to illustrate how to call rest via python to help you get started and not a supported code,
You have an example on how to call the Obtain token API in the RESTful API 1.4 Guide for 3.0.x,
And explanation about tokens in the above Article and RESTful API 1.4 Guide for 3.0.x. 

Create Policy example:



List Policies example:

  
Delete Policy example:



Thanks for reading this guide,
N2WS Support Team.

    • Related Articles

    • CPM RESTful API guide

      Attached to this article is the user guide for CPM RESTful API v1.3 (for CPM v2.6.0 and up). For CPM CLI information see here: https://support.n2ws.com/portal/kb/articles/cli-guide-and-software-download-for-cpm-v2-6-0 You can find the latest version ...
    • RestAPI example files

      Background: CPM contain rich RESTful API interface that enable you to do everything you do manually in the UI in an automated way, but it can be difficult to start using the RESTful API. We created this examples to assist customers in understanding ...
    • CLI guide and software download for CPM v4.0.0

      CLI v2.0 for CPM v4.0.0 and the user guide are available for download as attachments to this solution Previous version: CLI guide and software download for CPM v3.2.1x  Next version: CLI guide and software download for CPM v4.1.0x
    • Recovering instance in v2.6.0a (only) via REST API may result in error 500 and the "AttributeError: 'unicode' object has no attribute 'aws_region'" exception

      The problem is on v2.6.0a, in REST, recovery might fail with error 500 and in the CPM UI it looks in progress. The following errors may be logged: ERROR    MainThread   cpmrequest.py   151   call                                          API Request ...
    • Getting started with N2WS version 3.0.x

      Background In this guide you can find few materials such as videos, documents and Articles to help you get started with N2WS backup & recovery version 3.0.0. For the full information about the product, please have a look at our N2WS ...