UltraDNS Zone Snapshot and Restore - API documentation

https://api.ultradns.com/

Welcome

This document lists the version of UltraDNS Zone Snapshot and Restore API endpoints, supported http methods, and sample requests and responses.

In UltraDNS, a backup is also known as a Snapshot. A zone snapshot represents the state of a zone (i.e. primarily its RRSet configuration) at the time the Snapshot is created.
Performing a zone Restore uses the most recent zone snapshot, and overwrites the zone's current configuration with that of the one stored in the Snapshot. The zone snapshot can be restored at any point in time, as long as the zone meets the required criteria.

Important:

Snapshot or Restore activity is final and cannot be rolled-back.
A zone can have a maximum of one Snapshot at a time. In other words, a zone snapshot request will either create a Snapshot (if it does not already exist), or will overwrite the existing Snapshot (if it already exist).
Snapshot or Restore is only allowed for zones that meet the following criteria:

Snapshot and Restore only supports primary zones.
The zone should not have more than 50,000 records, including the allowed pool's resource records.
The zone should only have:

Basic Resource Records.
Resource Distribution Pools
Directional DNS Pools
Load Balancing pools
Simple Monitor / Failover pools
Simple Load Balancing pools
Web Forwarding

The zone should not have:

Mail Forwarding

Additionally, the Snapshot and Restore functions do not support the following types of zones:

Signed zones
Secondary zones
Alias zones
Suspended zones

If a Zone Snapshot contains a Directional (DIR) pool with Global Account Level GEO and Source IP groups, once the Restore operation is completed, the Account level GEO and Source IP gruops will be converted to the local pool level groups.
To further clarify the previous point about the Restore functionality, a zone must also satisfy the above criteria at the time of the Restore operation. For example, if a zone was signed after a Snapshot was created, or a directional pool was added, or the number of records exceeded 50,000, the Restore operation will not be allowed.
Snapshot or Restore is a background activity; it is highly recommended to refrain from performing any activity that could change the zone configuration while a Snapshot or Restore is in-progress. Doing so might lead to data inconsistency or other unexpected results.
A user with basic READ permissions on a zone and its resource records may be allowed to take a zone Snapshot, but might require full READ, WRITE, UPDATE and DELETE permissions on the zone and all of its resource records to Restore a Snapshot.

Authorization

Users need to authenticate in order to receive a bearer token that they can use throughout their session while interacting with our APIs.
Once you have an access_token, use it in the request headers to provide authorization for subsequent requests:
Authorization: Bearer <access_token>

/authorization/token post

post

Generates a new bearer token that can be used in the request headers to provide authorization for subsequent requests.

Request
Response

Body

Media type: application/x-www-form-urlencoded

Type: object

Properties

grant_type: required(string)
The grant type, pass password to get the access token.
username: required(string)
The UltraDNS username.
password: required(string)
The UltraDNS password.

HTTP status code 200

OK message returned with token_type, refresh_token, access_token, and expires_in data.

Body

Media type: application/json

Type: object

Properties

access_token: required(string)
The access token, used to provide your identity on subsequent REST API calls.

Example:

{
  "token_type": "Bearer",
  "refresh_token": "b42f9923c71e454bbf475c23b07275a19d6393ecc6",
  "access_token": "22bcb99d109e4cebb9ca717ac6",
  "expires_in": "3600"
}

HTTP status code 400

Returned for an invalid grant_type, or missing form parameter (username or password).

Body

Media type: application/json

Type: any

Example:

[
  {
    "errorCode": 60005,
    "errorMessage": "grant_type not supported"
  }
]

[
  {
  "errorCode": 60007,
  "errorMessage": "invalid_request: Username parameter is required for grant_type=password."
  }
]

[
  {
    "errorCode": 60008,
    "errorMessage": "invalid_request: Password parameter is required for grant_type=password."
  }
]

HTTP status code 401

Returned for an invalid username or password.

Body

Media type: application/json

Type: any

Example:

[
  {
  "errorCode": 60001,
  "errorMessage": "invalid_grant: Invalid username & password combination."
  }
]

List Zones

Returns the list of zone names that are eligible for Snapshot and Restore. Any pre-existing snapshot date for a zone will be displayed as well.

/zones/snapshot-eligible get

get

Returns the list of eligible zones and the existing Snapshot date with description, if any exist.

Secured by Bearer Authentication

Each request must contain the bearer token in the Authorization header when making requests to protected resources.

Query Parameters

q: (string)
The query used to construct the list. Operators are "name":(partial string matches).
Example:/zones?q=name:abc
offset: (integer)
The position in the list for the first returned element (0 based). Default value 0.
limit: (integer)
The maxiumum number of rows requested. Default value 100.
reverse: (boolean)
Whether the list is ascending (false) or descending (true). Default value is false.

HTTP status code 200

OK message returned with Zone List DTO data.

Body

Media type: application/json

Type: object

Properties

zones: (array)
The list of the zone objects, which includes the domain name and possible Snapshot date.
zoneName: (string)
The Zone name.
snapshots: (array)
The stored Snapshot information (if available).
date: (string)
The date and time of the latest available Snapshot (in ISO 8601 format).
description: (string)
The description for the Zone Snapshot.
totalCount: (integer)
The total count of all of the zones found for the specified query.
returnedCount: (integer)
The total number of records returned.

Example:

{
  "zones": [
    {
      "zoneName": "abc.com.",
      "snapshots": [
        {
          "date": "2018-09-24T14:59:18.208Z",
		  "description": "Description for snapshot purpose"
        }
      ]
    },
    {
      "zoneName": "abc1.com.",
      "snapshots": [
        {
          "date": "2018-12-03T10:509:38.208Z",
		  "description": "Description for snapshot purpose"
        }
      ]
    }
  ],
  "queryInfo": {
    "q": "",
    "limit": 100,
    "reverse": false
  },
  "resultInfo": {
    "totalCount": 2,
    "offset": 0,
    "returnedCount": 2
  }
}

HTTP status code 404

Returned for data not found in the system for the provided input, or for zones not eligible for Snapshot.

Body

Media type: application/json

Type: any

Example:

{
  "errorCode": 70002,
  "errorMessage": "Data not found."
}

Secured by Bearer Authentication

Headers

Authorization: required(string)
Used to send the bearer token in the format Bearer <access_token>.

HTTP status code 401

Unauthorized. Either the provided bearer token is invalid, expired or the user is not allowed to access the content provided by the requested URL.

Create, Retrieve, and Delete a Snapshot of a Zone

Create a Snapshot of your zone allowing you to save your current zone configuration settings. Once created, you can retrieve the snapshot details. If you no longer need the Snapshot of the zone, you can delete it.
Note - Any user with Read permissions for the zone can create a Snapshot.

/zones/{zoneName}/snapshot post get delete

post

Create a Snapshot of a Zone - Deletes previously saved Snapshots of the zone.

get

Get Snapshot of a Zone.

delete

Delete the snapshot of a Zone.

Get Snapshot of a Zone.

Secured by Bearer Authentication

Each request must contain the bearer token in the Authorization header when making requests to protected resources.

URI Parameters

zoneName: required(string)

HTTP status code 200

OK message returned with the Zone Snapshot DTO details returned.

Body

Media type: application/json

Type: any

Example:

{
	"zoneName": "00-ben-doc-test.com",
	"rrSets": [
		{
			"ownerName": "def.00-ben-doc-test.com.",
			"rrtype": "A (1)",
			"ttl": 300,
			"rdata": [
				"204.74.99.100"
			]
		},
		{
			"ownerName": "00-ben-doc-test.com.",
			"rrtype": "NS (2)",
			"ttl": 500,
			"rdata": [
				"udns1.ultradns.net.",
				"udns2.ultradns.net."
			]
		},
		{
			"ownerName": "00-ben-doc-test.com.",
			"rrtype": "SOA (6)",
			"ttl": 500,
			"rdata": [
				"udns1.ultradns.net. rajender\\.aindla.example.biz. 2018032603 10800 3600 2592000 86400"
			]
		},
		{
			"ownerName": "abc.com.00-ben-doc-test.com.",
			"rrtype": "A (1)",
			"ttl": 300,
			"rdata": [
				"204.74.99.100"
			]
		},
		{
			"ownerName": "rd.00-ben-doc-test.com.",
			"rrtype": "A (1)",
			"ttl": 300,
			"rdata": [
				"3.4.5.6"
			],
			"profile": {
				"description": "rd pool",
				"order": "ROUND_ROBIN",
				"@context": "http://schemas.ultradns.com/RDPool.jsonschema"
			}
		},
		{
			"ownerName": "dir-geo.00-ben-doc-test.com.",
			"rrtype": "A (1)",
			"rdata": [
				"2.2.2.2",
				"4.3.4.3"
			],
			"profile": {
				"description": "geo",
				"conflictResolve": "GEO",
				"rdataInfo": [
					{
						"ipInfo": {
							"ips": [
								{
									"start": "1.1.1.1",
									"end": "2.2.2.2"
								}
							],
							"name": "accountIPGroup"
						},
						"ttl": 600,
						"type": "A"
					},
					{
						"geoInfo": {
							"name": "localGeo",
							"codes": [
								"EUR"
							]
						},
						"ipInfo": {
							"ips": [
								{
									"start": "2.3.4.5",
									"end": "2.3.4.6"
								}
							],
							"name": "localIP"
						},
						"ttl": 300,
						"type": "A"
					}
				],
				"@context": "http://schemas.ultradns.com/DirPool.jsonschema"
			}
		},
		{
			"ownerName": "sb.00-ben-doc-test.com.",
			"rrtype": "A (1)",
			"ttl": 500,
			"rdata": [
				"abc.com.",
				"1.2.3.4"
			],
			"profile": {
				"description": "SB",
				"runProbes": false,
				"actOnProbes": true,
				"order": "ROUND_ROBIN",
				"maxActive": 1,
				"maxServed": 0,
				"rdataInfo": [
					{
						"state": "NORMAL",
						"runProbes": true,
						"priority": 1,
						"failoverDelay": 0,
						"threshold": 1,
						"availableToServe": true
					},
					{
						"state": "NORMAL",
						"runProbes": true,
						"priority": 1,
						"failoverDelay": 0,
						"threshold": 1,
						"availableToServe": true
					}
				],
				"probes": [
					{
						"id": "060845B113499BEA",
						"type": "HTTP",
						"interval": "FIFTEEN_MINUTES",
						"agents": [
							"ASIA",
							"CHINA"
						],
						"threshold": 2,
						"details": {
							"transactions": [
								{
									"method": "GET",
									"url": "https://google.co.in/",
									"transmittedData": "",
									"limits": {
										"connect": {
											"fail": 20
										},
										"run": {
											"fail": 60
										}
									},
									"followRedirects": true
								}
							]
						}
					}
				],
				"notifications": [
					{
						"poolRecords": [
							{
								"poolRecord": "abc.com.",
								"notification": {
									"probe": true,
									"record": false,
									"scheduled": false
								}
							},
							{
								"poolRecord": "1.2.3.4",
								"notification": {
									"probe": true,
									"record": true,
									"scheduled": true
								}
							}
						],
						"email": "abc@abc.com"
					}
				],
				"events": [
					{
						"id": "060845B113499BE6",
						"poolRecord": "abc.com.",
						"type": "NORMAL",
						"start": "2018-05-14T05:30:00+05:30",
						"end": "2030-01-01T05:30:00+05:30",
						"notify": "NEVER"
					}
				],
				"status": "OK",
				"@context": "http://schemas.ultradns.com/SBPool.jsonschema"
			}
		}
	],
	"webForwards": [
		{
			"guid": "090845B113499BEB",
			"requestTo": "abc.com.00-ben-doc-test.com/requestTo.html",
			"defaultRedirectTo": "http://abc.com/redirectTo.html",
			"defaultForwardType": "HTTP_301_REDIRECT"
		}
	]
}

Secured by Bearer Authentication

Headers

Authorization: required(string)
Used to send the bearer token in the format Bearer <access_token>.

HTTP status code 401

Unauthorized. Either the provided bearer token is invalid, expired or the user is not allowed to access the content provided by the requested URL.

Restore Zone Snapshot

Replaces your current zone configuration with the most recently saved Snapshot of your zone.

/zones/{zoneName}/restore post

post

Restore the Zone Snapshot.

Secured by Bearer Authentication

Each request must contain the bearer token in the Authorization header when making requests to protected resources.

URI Parameters

zoneName: required(string)

HTTP status code 202

Accepted message returned with a header X-Task-Id.

Headers

application/json: required(string)

Example:

Access-Control-Allow-Credentials → true

Access-Control-Allow-Headers → Origin, X-Requested-With, Content-Type, Accept, Authorization

Access-Control-Allow-Methods → POST, GET, OPTIONS, DELETE, PUT, PATCH

Access-Control-Allow-Origin → *

Access-Control-Max-Age → 3600

Connection → keep-alive

Content-Length → 0

Date → Thu, 03 May 2018 20:00:16 GMT

X-Task-Id → 478a8463-63aa-4ae2-aea0-f73eb37ac9d0

HTTP status code 400

Returned for an invalid Zone Name, permission violations, or if the zone is not eligible for Snapshot.

Body

Media type: application/json

Type: any

Example:

{
  "errorCode": 280008,
  "errorMessage": "Operation not allowed: please verify the zone name, your permissions on the zone, and whether the zone meets the required criteria."
}

HTTP status code 404

Returned if a Zone snapshot does not exist for the zone.

Body

Media type: application/json

Type: any

Example:

{
        "errorCode": 280005,
        "errorMessage": "Zone snapshot does not exist."
}

Secured by Bearer Authentication

Headers

Authorization: required(string)
Used to send the bearer token in the format Bearer <access_token>.

HTTP status code 401

Unauthorized. Either the provided bearer token is invalid, expired or the user is not allowed to access the content provided by the requested URL.

UltraDNS Zone Snapshot and Restore - API documentation

Welcome

Snapshot and Restore

Authorization

/authorization/token post

post /authorization/token

Body

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

List Zones

/zones/snapshot-eligible get

get /zones/snapshot-eligible

Query Parameters

HTTP status code 200

Body

HTTP status code 404

Body

Secured by Bearer Authentication

Headers

HTTP status code 401

Create, Retrieve, and Delete a Snapshot of a Zone

/zones/{zoneName}/snapshot post get delete

post /zones/{zoneName}/snapshot

URI Parameters

Body

Secured by Bearer Authentication

Headers

HTTP status code 401

get /zones/{zoneName}/snapshot

URI Parameters

HTTP status code 200

Body

Secured by Bearer Authentication

Headers

HTTP status code 401

delete /zones/{zoneName}/snapshot

URI Parameters

HTTP status code 204

Secured by Bearer Authentication

Headers

HTTP status code 401

Restore Zone Snapshot

/zones/{zoneName}/restore post

post /zones/{zoneName}/restore

URI Parameters

HTTP status code 202

Headers

HTTP status code 400

Body

HTTP status code 404

Body

Secured by Bearer Authentication

Headers

HTTP status code 401