Struct Zones 

pub struct Zones<'a> { /* private fields */ }

Zone routes, from Client::zones.

A zone is addressed by its uuid or its name ("example.com"). Access: a personal key reaches the zones its user is a member of; a zone key only its own zone.

Implementations

impl<'a> Zones<'a>

pub async fn list(&self, page: PageRequest) -> Result<Page<Zone>>

Zones visible to the caller. Core paginates only for an Admin; everyone else gets their whole list on one page. Prefer list_all unless you page yourself.

GET /api/v1/zones

pub async fn list_all(&self) -> Result<Vec<Zone>>

All visible zones, following pagination.

GET /api/v1/zones, as many times as there are pages.

pub async fn get(&self, zone: &str) -> Result<Zone>

One zone by uuid or name.

GET /api/v1/zones/:ref

Errors

ErrorCode::NotFound if there is no such zone.

Examples

let zone = client.zones().get("example.com").await?;
println!("{} is {}", zone.name, zone.uuid);

pub async fn create(&self, name: &str) -> Result<Zone>

Creates a zone; the caller becomes its Owner and Core adds the apex SOA and NS. Not allowed with a zone-scoped key.

A name directly below a free domain (FreeDomains::list) is a lease: one label of 3–63 characters, not reserved, not taken, and at most the free domains’ limit leases per user. Core then also delegates the name from the free domain.

POST /api/v1/zones

Errors

• ErrorCode::Conflict if the zone already exists, or a lease breaks a rule (details says which, e.g. the lease limit).
• ErrorCode::Validation if the name is not a valid domain name.
• ErrorCode::Forbidden with a zone key, or for a free domain itself (Admin only).

pub async fn create_api_key(&self, zone: &str) -> Result<Secret>

Issues a new zone-scoped key (dz_…) and returns it. Core shows the key only in this response and keeps just its hash, so store it now. A previous key of the zone stops working immediately; if it is the key this client uses, build a new client with the new key. Allowed for the zone’s own key, its Owner or Administrator, and Admin.

POST /api/v1/zones/:ref/api-key

Errors

ErrorCode::NotFound if there is no such zone.

Examples

let key = client.zones().create_api_key("example.com").await?;
// Show the key to the user now; Core never returns it again.
println!("{}", key.expose());

pub async fn revoke_api_key(&self, zone: &str) -> Result<Zone>

Revokes the zone’s key; the zone then has none (Zone::has_api_key is false). Same access as create_api_key.

DELETE /api/v1/zones/:ref/api-key

Errors

ErrorCode::NotFound if there is no such zone.

pub async fn delete(&self, zone: &str) -> Result<()>

Deletes the zone with all its records, geo bans and health checks. Irreversible. Allowed for the zone’s Owner, an Admin or the zone’s own key; a delegated Administrator may not.

DELETE /api/v1/zones/:ref

Errors

• ErrorCode::NotFound if there is no such zone.
• ErrorCode::Forbidden if the caller is not the Owner.

pub async fn export(&self, zone: &str, format: ZoneFileFormat) -> Result<String>

The zone as a file, exactly as Core writes it. Json is the dinio-zone document (parse it into ZoneDocument if needed); Bind and Csv carry only name, ttl, type and data. Reading is enough, so it works on a suspended zone too.

GET /api/v1/zones/:ref/export?format=

Errors

ErrorCode::NotFound if there is no such zone.

Examples

use dinio_sdk::models::ZoneFileFormat;

let zone_file = client.zones().export("example.com", ZoneFileFormat::Bind).await?;
std::fs::write("example.com.zone", zone_file).expect("write");

pub async fn import( &self, zone: &str, format: ZoneFileFormat, file: String, dry_run: bool, ) -> Result<ImportReport>

Merges a zone file into the zone: adds what the zone lacks, never changes or deletes anything. SOA and apex NS in the file are skipped. Records are written in one transaction (all or none); redirects of a dinio-zone document afterwards, each on its own. With dry_run Core checks everything and writes nothing.

POST /api/v1/zones/:ref/import?format=&dry_run=

Errors

• ErrorCode::ImportFailed if any record is refused: nothing was written, and ApiError::import_report has the report. A dry run returns the same report as Ok instead.
• ErrorCode::PayloadTooLarge for a file over 2 MiB (at most 10 000 records).
• ErrorCode::Validation if a dinio-zone document does not have the expected shape.
• ErrorCode::Suspended for a suspended zone.
• ErrorCode::NotFound if there is no such zone.

Examples

use dinio_sdk::models::ZoneFileFormat;

let file = std::fs::read_to_string("example.com.zone").expect("read");
let zones = client.zones();
let preview = zones.import("example.com", ZoneFileFormat::Bind, file.clone(), true).await?;
if !preview.has_errors() {
    let report = zones.import("example.com", ZoneFileFormat::Bind, file, false).await?;
    println!("{} records created", report.records.created);
}

pub async fn discover( &self, zone: &str, nameservers: &[String], ) -> Result<Discovery>

Asks the zone’s current nameservers (the previous provider’s) about the names a zone usually has and returns a proposal to review, trim and pass to import. Writes nothing. Finds common names only, not every record (AXFR is refused almost everywhere). Takes up to about a minute, so the request waits at least 90 s whatever the client’s timeout.

nameservers (host names or addresses, at most 8) are needed once the delegation already points to Dinio; empty means “ask the delegation”.

POST /api/v1/zones/:ref/discover

Errors

• ErrorCode::DiscoveryFailed if no usable nameserver answered; typically the delegation already points to Dinio, so give the previous provider’s nameservers.
• ErrorCode::Conflict while a discovery of the zone is running.
• ErrorCode::Suspended for a suspended zone.
• ErrorCode::NotFound if there is no such zone.

Examples

use dinio_sdk::models::ZoneFileFormat;

let found = client.zones().discover("example.com", &[]).await?;
let mut document = found.document;
document.records.retain(|r| r.record_type != "TXT");
let file = serde_json::to_string(&document).expect("serializable");
client.zones().import("example.com", ZoneFileFormat::Json, file, false).await?;