dinio_sdk/lib.rs
1//! Rust SDK for the Dinio platform API (Core REST API, `/api/v1`).
2//!
3//! # Quick start
4//!
5//! ```no_run
6//! use dinio_sdk::Client;
7//! use dinio_sdk::ops::{self, AddValue};
8//!
9//! # async fn example() -> dinio_sdk::Result<()> {
10//! let client = Client::builder()
11//! .base_url("https://api-dinio.bitelex.com")
12//! .api_key("du_...")
13//! .build()?;
14//!
15//! // Zones are addressed by name or uuid.
16//! let zone = client.zones().get("example.com").await?;
17//!
18//! // Core wants full owner names; `qualify_name` turns zone-file style names into them.
19//! let name = ops::qualify_name("www", &zone.name)?;
20//! let added = ops::add_value(
21//! &client,
22//! &zone,
23//! &name,
24//! "A",
25//! AddValue { data: "192.0.2.10".into(), ..Default::default() },
26//! )
27//! .await?;
28//! println!("added {} (TTL {})", added.value.data, added.ttl);
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! # Layers
34//!
35//! * [`api`]: one method per Core route, reached from the [`Client`] (`client.zones()`,
36//! `client.records()`, ...). Resources are addressed by uuid, as Core does. Use it when
37//! you keep uuids yourself.
38//! * [`ops`]: name-based operations composed from `api` calls: a record value by its
39//! (name, type, data), geo bans by area name, owner names zone-file style.
40//! * [`models`]: the wire shapes of Core resources.
41//!
42//! # Authentication
43//!
44//! A Core-issued API key, sent as `Authorization: Bearer <key>`: either a personal key
45//! (`du_…`, access to every zone the user is a member of) or a zone key (`dz_…`, access to
46//! that one zone); [`ApiKeyKind::of`] tells them apart. Core shows a key only once, when it
47//! issues it ([`api::Zones::create_api_key`], [`api::Users::create_api_key`]), and keeps
48//! only its hash. Core decides what a key may do; the SDK does not repeat its rules.
49//!
50//! # Errors
51//!
52//! Every call returns [`Result`]. [`Error::Api`] keeps Core's `error.code`, message and
53//! details; the other variants say whether the request was never answered, the answer was
54//! not Core's, or the SDK refused the input before sending anything.
55//!
56//! # Runtime
57//!
58//! The SDK is async, starts no runtime and spawns no tasks. The HTTP layer (`reqwest`)
59//! needs a tokio runtime to poll the returned futures.
60
61#![warn(missing_docs)]
62
63pub mod api;
64mod auth;
65mod client;
66mod envelope;
67mod error;
68pub mod models;
69pub mod ops;
70mod time;
71
72pub use auth::{ApiKeyKind, Credentials, Secret};
73pub use client::{Client, ClientBuilder};
74pub use envelope::{CursorPage, Meta, Page};
75pub use error::{ApiError, Error, ErrorCode, Result};
76pub use time::Timestamp;
77pub use uuid::Uuid;