Crate nym_http_api_client 

Nym HTTP API Client

Centralizes and implements the core API client functionality. This crate provides custom, configurable middleware for a re-usable HTTP client that takes advantage of connection pooling and other benefits provided by the reqwest Client.

Making GET requests

Create an HTTP Client and use it to make a GET request.

let url: Url = "https://nymvpn.com".parse()?;
let client = nym_http_api_client::Client::new(url, None);

// Send a get request to the `/v1/status` path with no query parameters.
let resp = client.send_get_request(&["v1", "status"], NO_PARAMS).await?;
let body = resp.text().await?;

println!("body = {body:?}");

JSON

There are also json helper methods that assist in executing requests that send or receive json. It can take any value that can be serialized into JSON.

use nym_http_api_client::{ApiClient, HttpClientError, NO_PARAMS};

#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
pub struct ApiHealthResponse {
    pub status: ApiStatus,
    pub uptime: u64,
}

#[derive(Clone, Copy, Debug, Serialize, Deserialize)]
pub enum ApiStatus {
    Up,
}

// This will POST a body of `{"lang":"rust","body":"json"}`
let mut map = HashMap::new();
map.insert("lang", "rust");
map.insert("body", "json");

// Create a client using the ClientBuilder and set a custom timeout.
let client = nym_http_api_client::Client::builder("https://nymvpn.com")?
    .with_timeout(Duration::from_secs(10))
    .build()?;

// Send a POST request with our json `map` as the body and attempt to parse the body
// of the response as an ApiHealthResponse from json.
let res: ApiHealthResponse = client.post_json(&["v1", "status"], NO_PARAMS, &map)
    .await?;

Creating an ApiClient Wrapper

An example API implementation that relies on this crate for managing the HTTP client.

use nym_http_api_client::{ApiClient, HttpClientError, NO_PARAMS};

mod routes {
    pub const API_VERSION: &str = "v1";
    pub const API_STATUS_ROUTES: &str = "api-status";
    pub const HEALTH: &str = "health";
}

mod responses {
    #[derive(Clone, Copy, Debug, Serialize, Deserialize)]
    pub struct ApiHealthResponse {
        pub status: ApiStatus,
        pub uptime: u64,
    }

    #[derive(Clone, Copy, Debug, Serialize, Deserialize)]
    pub enum ApiStatus {
        Up,
    }
}

mod error {
    #[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
    pub struct RequestError {
        message: String,
    }

    impl Display for RequestError {
        fn fmt(&self, f: &mut Formatter<'_>) -> FmtResult {
            Display::fmt(&self.message, f)
        }
    }
}

pub type SpecificAPIError = HttpClientError;

#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
pub trait SpecificApi: ApiClient {
    async fn health(&self) -> Result<responses::ApiHealthResponse, SpecificAPIError> {
        self.get_json(
            &[
                routes::API_VERSION,
                routes::API_STATUS_ROUTES,
                routes::HEALTH,
            ],
            NO_PARAMS,
        )
        .await
    }
}

impl<T: ApiClient> SpecificApi for T {}

Re-exports

pub use dns::HickoryDnsResolver;

pub use dns::ResolveError;

pub use inventory;

pub use reqwest;

Modules

dns

DNS resolver configuration for internal lookups.

registry

Global registry for HTTP client configurations.

Macros

generate_user_agent

Create UserAgent based on the caller’s crate information

Structs

Client

A simple extendable client wrapper for http request with extra url sanitization.

ClientBuilder

A ClientBuilder can be used to create a Client with custom configuration applied consistently and state tracked across subsequent requests.

ReqwestClientBuilder

A ClientBuilder can be used to create a Client with custom configuration.

ReqwestErrorWrapper

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

Url

When configuring fronting, some configurations will require a specific backend host to be used for the request to be properly reverse proxied.

UserAgent

Characteristic elements sent to the API providing basic context information of the requesting client.

Enums

FrontPolicy

Policy for when to use domain fronting for HTTP requests.

HttpClientError

The Errors that may occur when creating or using an HTTP client.

SerializationFormat

Serialization format for API requests and responses

Constants

DEFAULT_TIMEOUT

Default HTTP request connection timeout.

NO_PARAMS

Empty collection of HTTP Request Parameters.

Traits

ApiClient

Common usage functionality for the http client.

ApiClientCore

Core functionality required for types acting as API clients.

IntoUrl

A trait to try to convert some type into a Url.

Functions

parse_response

Attempt to parse a response object from an HTTP response

Type Aliases

Params

Collection of HTTP Request Parameters

PathSegments

Collection of URL Path Segments