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!