diff --git a/src/api/mod.rs b/src/api/mod.rs index 69204c3..67c0968 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -12,12 +12,28 @@ use responses::{ pub mod endpoints; pub mod responses; +/// An API client used for interfacing with a specific CT log. This can be +/// constructed with [`CtApiClient::new`] to automatically create an inner +/// [`reqwest::Client`], or an [`Arc`] of one can be passed manually with +/// [`CtApiClient::new_with_client`] to re-use an existing client between code. +/// Re-using clients if one is already created is recommended, as it allows +/// connection-pools to be re-used and will have less overhead between requests. pub struct CtApiClient { inner_client: Arc, log_url: Url } impl CtApiClient { + /// Creates a new [`CtApiClient`] given a specific log URL. This log URL can + /// contain a subpath if the specific log uses one. Anything besides a + /// scheme, host information (ip/port), and a standard path is not supported + /// and will likely cause requests to fail. + /// + /// ## Errors + /// + /// As this automatically constructs a [`reqwest::Client`], this will error + /// if the client fails to be created for whatever reason, usually due to it + /// being unable to find TLS configuration and root store for the platform. pub fn new(log_url: Url) -> reqwest::Result { Ok(Self { inner_client: Arc::new(reqwest::Client::builder().https_only(true).build()?), @@ -25,6 +41,11 @@ impl CtApiClient { }) } + /// Creates a new [`CtApiClient`] given a specific log URL and + /// [`reqwest::Client`]. This log URL can contain a subpath if the specific + /// log uses one. Anything besides a scheme, host information (ip/port), + /// and a standard path is not supported and will likely cause requests to + /// fail. pub fn new_with_client(log_url: Url, inner_client: Arc) -> Self { Self { inner_client,