gleif_rs/
lib.rs

1//! # GLEIF API Client Library ([`gleif_rs`](crate))
2//!
3//! This Rust library provides a type-safe, ergonomic client for interacting with the [Global Legal Entity Identifier Foundation (GLEIF) API](https://www.gleif.org/en/lei-data/gleif-api).
4//! Whether you're retrieving LEI records, filtering data, or managing API responses, this library ensures seamless integration with strong typing and clear error handling.
5//!
6//! ## Features
7//!
8//! - **Simple API Requests:** Easily fetch and filter LEI records via the fluent interface ([`crate::client::GleifClient::lei_records`]).
9//! - **Type-Safe Fields & Values:** Use enums like [`crate::field::Field`] and [`crate::value::EntityCategory`] to avoid typos and invalid values.
10//! - **Comprehensive Error Handling:** Centralized error management via [`crate::error::GleifError`].
11//! - **Customizable Requests:** Build and refine API queries with [`crate::request_builder::GleifRequestBuilder`].
12//! - **Extensible HTTP Client:** Bring your own [`reqwest::Client`] or use middleware for retries, logging, and more.
13//!
14//! ## Getting Started
15//!
16//! Run the following Cargo command in your project directory:
17//!
18//! ```shell
19//! cargo add gleif-rs
20//! ```
21//!
22//! ### Basic Example: Fetching an LEI Record
23//!
24//! The following example demonstrates how to fetch a specific LEI record using its ID.
25//!
26//! ```rust
27//! use gleif_rs::{
28//!     client::GleifClient,
29//!     error::GleifError,
30//!     model::LeiRecord,
31//! };
32//!
33//! #[tokio::main]
34//! async fn main() -> Result<(), GleifError> {
35//!     // Initialize the GLEIF client
36//!     let client = GleifClient::new();
37//!     // Fetch a specific LEI record by its ID
38//!     let lei_record: LeiRecord = client.lei_record_by_id("5493001KJTIIGC8Y1R12").await?;
39//!
40//!     println!("LEI Record: {lei_record:#?}");
41//!     Ok(())
42//! }
43//! ```
44//!
45//! ### Filtering LEI Records
46//!
47//! You can refine your API queries using filters:
48//!
49//! ```rust
50//! use gleif_rs::{
51//!     client::GleifClient,
52//!     error::GleifError,
53//!     field::Field,
54//!     model::LeiRecordList,
55//!     value::{EntityCategory, RegistrationStatus},
56//! };
57//!
58//! #[tokio::main]
59//! async fn main() -> Result<(), GleifError> {
60//!     // Initialize the GLEIF client
61//!     let client = GleifClient::new();
62//!     // Fetch LEI records with specific filters
63//!     let lei_records: LeiRecordList = client
64//!         .lei_records()
65//!         .filter_eq(Field::EntityCategory, EntityCategory::Fund)
66//!         .filter_eq(Field::RegistrationStatus, RegistrationStatus::Issued)
67//!         .sort(Field::EntityLegalName)
68//!         .page_size(10)
69//!         .send()
70//!         .await?;
71//!
72//!     println!("Found {} matching records.", lei_records.data.len());
73//!     Ok(())
74//! }
75//! ```
76//!
77//! ### Advanced Configuration: Custom HTTP Client
78//!
79//! For greater control over API requests, such as retry policies and timeouts,
80//! you can customize the underlying HTTP client:
81//!
82//! ```rust
83//! use gleif_rs::client::GleifClient;
84//! use reqwest::Client as ReqwestClient;
85//! use reqwest_middleware::ClientBuilder;
86//! use reqwest_retry::{RetryTransientMiddleware, policies::ExponentialBackoff};
87//! use std::time::Duration;
88//!
89//! #[tokio::main]
90//! async fn main() {
91//!     let reqwest_client = ReqwestClient::builder()
92//!         .timeout(Duration::from_secs(30))
93//!         .connect_timeout(Duration::from_secs(5))
94//!         .build()
95//!         .expect("Failed to create reqwest client");
96//!     let retry_policy = ExponentialBackoff::builder().build_with_max_retries(3);
97//!     let middleware = ClientBuilder::new(reqwest_client)
98//!         .with(RetryTransientMiddleware::new_with_policy(retry_policy))
99//!         .build();
100//!     let client = GleifClient::from_middleware_client(middleware);
101//!     println!("GLEIF client initialized with custom middleware: {}", client.base_url());
102//! }
103//! ```
104//!
105//! ## Error Handling
106//!
107//! All API methods return [`crate::error::Result`]. See the [`crate::error`] module for details.
108//!
109//! ## License
110//!
111//! This project is licensed under the MIT License. See [LICENSE](https://github.com/gleif-rs/gleif-rs/blob/main/LICENSE) for details.
112//!
113//! ---
114//!
115//! Feel free to explore and extend its capabilities based on your needs!
116
117pub mod client;
118pub mod endpoint;
119pub mod error;
120pub mod field;
121pub mod model;
122pub mod request_builder;
123#[cfg(test)]
124pub mod test_utils;
125pub mod value;
126
127/// Library version
128pub const VERSION: &str = env!("CARGO_PKG_VERSION");
129
130/// The default base URL for the GLEIF API v1.
131pub const DEFAULT_BASE_URL: &str = "https://api.gleif.org/api/v1/";
gleif_rs/lib.rs

gleif_rs/
lib.rs
