Restful API examples

Restful API examples

The purpose of this article is to help you get started with N2WS Restful API 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. N2WS Documentation
Environment: These examples were created using N2WS version 4.1.1a and RESTful-API-Guide-v2.1.0.pdf


How To enable REST API 

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 only to obtain access & refresh tokens.

The Access Token is used in all following API calls and is valid for 1 hour 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 Guide

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.

How to obtain tokens using cURL


obtain token Parameters:
  1. API_KEY='1f020e8ce04bd378a7705d4b91fcdcdef50324b3ba4eee915622f7e25d15ba1d9430d793c4aebe6e711034f51202f56389de4bf6a2569c96'
  2. HOST='ec2-55-133-273-21.compute-1.amazonaws.com'

obtain token API:
  1. curl -k -X POST https://$HOST/api/token/obtain/api_key/ -H 'Accept: application/json;' -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' -d '{"api_key": "'"$API_KEY"'"}' | jq

Results:

the jq module used at the end of the cURL commands 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
  1. ACCESS_TOKEN='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXQzOGE4NDA4YWQ4MDIiLCJhY2MiOiJDVVNUT01FUlMiLCJleHAiOjE1ODcyMDI2MzJ9.63VOViwDR3yYc6GTXlc9DJhOca4vOk7QPR5vUWtGAbk'
  2. REFRESH_TOKEN='eyJhbGciOiJIUzI1NiIsInR5XJfaWliMDI3MzRmOTJlNTNlIiwiYWNjIjoiQ1VTVE9NRVJTIiwiZXhwIjoxNTg3Mjg1NDMyfQ.jNPl2kyvxh7tqemRxLAGIKkbZ11a4u4W6yGqsiPLA1I'

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
  1. curl -k -X POST https://$HOST/api/token/refresh/ -H 'Accept: application/json;' -H 'Content-Type: application/json' -d '{"refresh": "'"$REFRESH_TOKEN"'"}' | jq

Result:


We will update the variable with the new value
  1. ACCESS_TOKEN='eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJanRpIjoiMDE0YWU4Y2VhODcwNDg5LCJhY2MiOiJDVVNUT01FUlMiLCJleHAiOjE1ODcyMDI4OTl9.4RxKdoeexz4bFCxR10Lt5ICTiK0emRp1a1-C0Ax6x6I'

You can find the more info in the restAPI Guide, Chapter 41.1. Generate Access & Refresh tokens


Various Rest API Examples

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. searching backup records.
We can use the the following CURL command to list all the AWS backup records:
  1. curl -k -X GET https://$HOST/api/aws/backups/ -H 'Accept: application/json;' -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
  1. curl -k -X GET https://$HOST/api/aws/backups/?status=B -H 'Accept: application/json;' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

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 ""
  1. 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. Run policy manually 
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
  1. curl -k -X GET "https://$HOST/api/aws/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
  1. POLICY_ID='2'
  2. curl -k -X POST "https://$HOST/api/aws/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
  1. curl -k -X GET https://$HOST/api/aws/backups/?tracker_id=1 -H 'Accept: application/json;' -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq


Additional Examples:
1. List schedule:
  1. 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
  1. curl -k -X GET "https://$HOST/api/aws/accounts/" -H "Accept: application/json;" -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq

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

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

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

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


What examples are available in the official guide?

In addition to all of the above examples, you also have the following examples available in our RESTful API Guide

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:
2.4. Python Script
  1. 2.4. Python Script - Obtain token, refresh token and get user list

Thanks for reading this guide,
N2WS Support Team.

    • Related Articles

    • 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 ...

    • CPM RESTful API guide for CPM v2.6.0

      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 ...

    • 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

    • Basic API example for CPM login and retrieving the list of CPM users using powershell

      The below script provides a basic example for the usage of CPM API with Powershell. Copy the below text into a .ps1 file, replace the text in blue with your relevant text and run the script.   ...

    • N2WS-18738 - Password saved as plain text for Recovery Scenario target added via RestAPI

      Issue: When creating Recovery Scenario(CPM v3.0 and up) and adding a backup target via Rest API, it will save the following details as plain text Proxy password for S3 instance recovery if used IAM AWS Secret Key when providing alternate Credential ...