v2.3.0

Summary

This release introduces several new endpoints and utilities that expand the capabilities of the SDK. Enhancements include support for health check and dangling CNAME endpoints, advanced report creation, zone snapshot management, and new utility classes for handling asynchronous responses related to tasks and reports.

New Feature(s)

Client Endpoints

• Health Check Endpoints

  • Added endpoints for initiating and retrieving health checks.
  • Issue #31
  • Example Usage:

    # The following will return a URI that is the location of a health check
    client.create_health_check('example.me')  # Example response: /v1/zones/example.me/healthchecks/2025-03-04T15:27:21.400Z
    # Retrieve the health check using the timestamp
    client.get_health_check('example.me', '2025-03-04T15:27:21.400Z')

• Dangling CNAME Endpoints

  • Added endpoints to create and retrieve dangling CNAME checks.
  • Issue #32
  • Example Usage:

    # The following will return a URI that is the location of a dangling CNAME check
    client.create_dangling_cname_check('example.me')  # Example response: /v1/zones/example.me/healthchecks/dangling/
    # Retrieve the dangling CNAME check
    client.get_dangling_cname_check('example.me')

  • Notes:
    • Dangling CNAME checks are a brand new feature in UltraDNS! Read more here.
    • Unlike health checks, only one dangling CNAME check is kept at a time for a zone, hence the omission of the timestamp.

• Advanced NX Domain Report & General Report Retrieval

  • Added an endpoint to create Advanced NX Domain Reports and a general endpoint for fetching report results.
  • Issue #33
  • Example Usage:

    # Request for reports returns a `requestId` in the response body
    client.create_advanced_nxdomain_report('2025-02-01', '2025-03-03', 'example.me')  # Example response: HQV_NXD-52abb89d-8ef5-4baa-b6c0-af8dfc163d0d
    # Retrieve the report manually using the reports endpoint
    client.get_report_results('HQV_NXD-52abb89d-8ef5-4baa-b6c0-af8dfc163d0d')

  • Notes:
    • Reports can take time to process; the API response will indicate if the report is still in process.
    • The "Advanced NXD Report" produces data on queries to non-existent hosts for a set of given zones, structured as follows:

      [
          {
              "zoneName": "example.me.",
              "hostName": "not-a-host.example.me.",
              "accountName": "myaccount",
              "startDate": "2025-02-01",
              "endDate": "2025-03-03",
              "rspTotal": 302,
              "nxdomainCount": 302
          }
      ]

• Projected Query Volume Report Endpoint

  • Added an endpoint to create a Projected Query Volume Report.
  • Issue #37
  • Example Usage:

    # The sortFields dict controls the order whereby results are displayed and is optional.
    # If not provided, default sort criteria are applied.
    client.create_projected_query_volume_report(
        accountName='abc',
        sortFields={
            'rspDaily': 'ASC',
            'ttlAvg': 'DESC',
            'rspMtd': 'ASC'
        }
    )
    # Example response: PQV-1b44abe9-24d4-4760-a312-c6f6c31a6abf

  • Notes:
    • Detailed documentation for the Projected Query Volume report is available here.

• Zone Query Volume Report Endpoint

  • Added an endpoint to create a Zone Query Volume Report.
  • Issue #38
  • Example Usage:

    client.create_zone_query_volume_report(
        '2016-05-10',     # startDate (YYYY-MM-DD)
        '2016-05-28',     # endDate (YYYY-MM-DD)
        zoneQueryVolume={ # Optional additional fields
            'zoneName': 'example.me.',
            'accountName': 'myaccount'
        },
        sortFields={      # Optional; defaults are applied if not provided
            'zoneName': 'DESC',
            'startDate': 'ASC',
            'endDate': 'DESC',
            'rspTotal': 'ASC'
        },
        offset=0,         # Optional pagination offset
        limit=1000        # Optional pagination limit
    )

  • Notes:
    • Detailed documentation for the Zone Query Volume Report is available here.

• Zone Snapshot Endpoints

  • Added endpoints for creating, retrieving, and restoring zone snapshots.
  • Issue #34
  • Example Usage:

    client.create_snapshot('example.me')  # Create a new snapshot
    client.get_snapshot('example.me')       # Retrieve the current snapshot
    client.restore_snapshot('example.me')   # Restore a zone to its snapshot state

  • Notes:
    • Only one snapshot of a zone can be kept at a time; creating a new snapshot overwrites the old one.
    • Use restore functionality with extreme caution as it is not reversible.

Utilities

Utilities are designed to handle repetitive workflows such as polling for background task completion. They are provided as isolated, optional submodules.

• TaskHandler Utility

  • Introduced the TaskHandler class to manage endpoints that return task_id or location responses, including automated polling until completion.
  • Issue #35
  • Example Usage:

    from ultra_rest_client import RestApiClient, TaskHandler
    client = RestApiClient('username', 'password')
    # For an endpoint that returns a task_id
    task_data = TaskHandler(
        client.create_snapshot('example.me'), 
        client
    )
    print(task_data)
    # For an endpoint that returns a location
    location_data = TaskHandler(
        client.create_health_check('example.me'), 
        client
    )
    print(location_data)

• ReportHandler Utility

  • Introduced the ReportHandler class to poll for report results based on a requestId.
  • Issue #36
  • Example Usage:

    from ultra_rest_client import RestApiClient, ReportHandler
    client = RestApiClient('username', 'password')
    # For an endpoint that returns a requestId for a report
    report = ReportHandler(
        client.create_advanced_nxdomain_report(
            startDate='2025-02-01', 
            endDate='2025-03-03', 
            zoneNames='example.me'
        ),
        client
    )

• Notes:

  • If an API call that returns neither a task_id, location, nor requestId is passed to the TaskHandler or ReportHandler, the original response is returned.
  • Additional documentation is available in src/ultra_rest_client/utils/README.md.

---

Additional Notes

• Detailed documentation and inline comments have been added for all new methods and classes.
• Example scripts demonstrating the usage of the new endpoints and utilities are available in the newly created examples directory.

---

We look forward to your feedback!

v2.2.5

New Feature(s)

Proxy Support & TLS Validation (PR#6)

• Added support for making requests through a proxy.

• Introduced a parameter to explicitly disable TLS validation when needed.

  >>> proxy_dict = {
  ...     "http": "http://192.168.1.243:9080",
  ...     "https": "http://192.168.1.243:9080"
  ... }
  >>> from ultra_rest_client import RestApiClient
  >>> client = RestApiClient('username', 'password', proxy=proxy_dict, verify_\
  https=False)
  >>> print(client.get_zones())
  {'queryInfo': {'q': '' ... } }
  

  mitmproxy  | [05:43:22.823][192.168.1.211:47424] client connect
  mitmproxy  | [05:43:22.849][192.168.1.211:47424] server connect api.ultradns.com:443 (3.86.127.106:443)
  mitmproxy  | 192.168.1.211:47424: POST https://api.ultradns.com/v1/authorization/token
  mitmproxy  |                   << 200 OK 304b
  mitmproxy  | [05:43:23.489][192.168.1.211:47424] client disconnect
  mitmproxy  | [05:43:23.490][192.168.1.211:47424] server disconnect api.ultradns.com:443 (3.86.127.106:443)
  mitmproxy  | [05:43:42.830][192.168.1.211:56532] client connect
  mitmproxy  | [05:43:42.857][192.168.1.211:56532] server connect api.ultradns.com:443 (35.175.76.156:443)
  mitmproxy  | 192.168.1.211:56532: GET https://api.ultradns.com/v1/zones
  mitmproxy  |                   << 200 OK 1.7k
  

• TLS validation warnings are now suppressed by default.

• Updated README.md with details on proxy usage and TLS validation options.

Resign Zone Method (PR#8)

• Added a method to resign DNSSEC-signed zones in the client wrapper.

Support for RD Pools (PR#7)

• Added a method for creating RD pools.

  Example Usage:

  # Demonstration of creating an A record RD pool
  client.create_rd_pool(
      "example.com", # Zone name
      "foo", # Hostname (owner)
      300, # TTL
      [
          "1.1.1.1", # List of rdata 
          "2.2.2.2", 
          "3.3.3.3"
      ]
  )
  
  # Demonstration of creating an AAAA pool
  client.create_rd_pool(
      "example.com", 
      "bar", 
      300, 
      [
          "2001:db8::1",
          "2001:db8::2", 
          "2001:db8::3"
      ], 
      ipv6=True, # Set AAAA to True
      order="RANDOM", # (Optional) Order of record distribution
      description="lorem ipsum" # (Optional) Description of pool
  )

• Added a method for replacing existing RD pools (PUT).

  Example Usage:

  client.edit_rd_pool(
      "example.com", 
      "bar", 
      600, 
      [
          "2001:db8::2", 
          "2001:db8::3"
      ], 
      ipv6=True, 
      order="FIXED", 
      description="ipsum"
  )

• Added a method for retrieving all RD pools.

  Example Usage:

  client.get_rd_pools("example.com")

• Added a delete method for removing an RD pool.

  Example Usage:

  client.delete_rd_pool("example.com", "foo")
  client.delete_rd_pool("example.com", "bar", ipv6=True)

• Updated README.md with RD pool example.

v2.2.4

Housekeeping

• modified file structure to be more aligned with best practices
• deleted old obsolete setup.py file
• fixed license section of README.md (Issue#26)
• updated .gitignore with common Python template
• made RestApiConnection class available in __init__.py
• fixed license_files in pyproject.toml (it excepts a list, not a dictionary)
• fixed version in about.py

New Feature(s)

Issue#28

• added constructors to RestApiClient and RestApiConnection classes to support custom HTTP headers (custom_headers)

  from ultra_rest_client import RestApiClient
  client = RestApiClient('username', 'password', custom_headers={"foo":"bar", "user-agent":"hello"})
  zones = client.get_zones()

  Captured header output:

  {
      "Accept": "application/json",
      "Authorization": "Bearer redacted",
      "Content-Type": "application/json",
      "foo": "bar",
      "user-agent": "hello",
      "User-Agent": "udns-python-rest-client-2.2.3"
  }

• added a public method to RestApiConnection which allows modification of headers after client has been instantiated

  client.rest_api_connection.set_custom_headers({"boo":"far","user-agent":"goodbye"})
  zones = client.get_zones()

  Captured header output:

  {
      "Accept": "application/json",
      "Authorization": "Bearer redacted",
      "Content-Type": "application/json",
      "foo": "bar",
      "boo": "far",
      "user-agent": "goodbye",
      "User-Agent": "udns-python-rest-client-2.2.3"
  }

• attempting to set the following headers will raise a ValueError

  • Content-Type
  • Authorization
  • Accept

• updated README.md with example

v2.2.3

adjustments to handling of x-task-id background tasks

v2.2.2

_do_call () of the connection does not handle background tasks and ACCEPTED http response codes

New parameter added to RestAPIClient constructor: use_token: bool = False

RestApiClient(bu: str, pr: str = None, use_token: bool = False, use_http: bool =False, host: str = "api.ultradns.com")
Initialize a Rest API Client.
Arguments:
bu (str) -- Either username or bearer token based on use_token flag.
pr (str, optional) -- Either password or refresh token based on use_token flag. Defaults to None.
use_token (bool, optional) -- If True, treats bu as bearer token and pr as refresh token. Defaults to False.

Keyword Arguments:
use_http (bool, optional) -- For internal testing purposes only, lets developers use http instead of https.
host (str) -- Allows you to point to a server other than the production server.

Raises:
ValueError -- If pr is not provided when use_token is True.

v2.1.1

updated company and contact information

v2.1.0

python module version increment

Adding v3 support for getting zones

Introduced two new functions get_zones_v3() and get_zone_metadata_v3() in addition to already present functions get_zones() and get_zone_metadata().