6 releases (3 stable)
new 1.0.2 | Oct 30, 2024 |
---|---|
0.1.2 | Oct 29, 2024 |
0.1.1 | Oct 28, 2024 |
0.1.0 | Oct 28, 2024 |
#393 in Web programming
262 downloads per month
87KB
1K
SLoC
loc-api
loc-api is a Rust library that provides a comprehensive interface for interacting with the Library of Congress (LOC) APIs. It simplifies the process of constructing API requests, managing parameters, and handling responses, enabling developers to seamlessly integrate LOC data into their Rust applications.
Features
- Comprehensive Endpoint Support: Access various LOC API endpoints such as search, collections, items, and resources.
- Flexible Parameter Management: Easily construct and customize query parameters, including filtering, sorting, and formatting options.
- Robust Response Models: Utilize well-defined Rust structures to parse and interact with LOC API responses.
- High-Level API Client: Engage with LOC APIs through an
ApiClient
that handles endpoint construction and HTTP requests. - Customizable Configurations: Override default settings like the base URL for testing or alternative deployments.
Table of Contents
Installation
Add loc-api
to your project's Cargo.toml
:
[dependencies]
loc-api = "*"
OR
You can use cargo add
to add the dependency to your Cargo.toml
:
cargo add loc-api
This library depends on reqwest
, serde
and serde_json
for making HTTP requests and serializing/deserializing JSON data, respectively:
[dependencies]
reqwest = { version = "0.11", features = ["blocking", "json"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
Examples
Creating an API Client
First, initialize the ApiClient
. You can optionally set the LOC_API_BASE_URL
environment variable to override the default LOC API base URL.
Other methods of setting the base URL include using the ApiClient::with_base_url
constructor or directly modifying the simple_builders::DEFAULT_BASE_URL
constant.
use loc_api::simple_builders::ApiClient;
fn main() {
let client = ApiClient::new();
// Now you can use `client` to interact with the LOC APIs
}
Using the modules directly to construct a URL for querying specific types of MediaType
use loc_api::{endpoints::*, param_models::*, format_models::*, attribute_models::*,
response_models::*};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let common_params = CommonParams {
format: Some(Format::Json),
attributes: Some(AttributesSelect {
include: vec!["pagination".to_string(), "results".to_string()],
exclude: vec![],
}),
query: Some("dog".to_string()),
filter: Some(FacetReq {
filters: vec!["subject:animals".to_string()],
}),
per_page: Some(25),
page: Some(1),
sort: Some(SortField::TitleS),
};
let format_params = CommonParams {
format: Some(Format::Json),
..common_params.clone()
};
let format_endpoint = Endpoints::Format {
format: MediaType::FilmAndVideos,
params: format_params,
};
let url = format_endpoint.to_url().unwrap();
println!("{}", url);
Ok(())
}
Using the simple_builders module to make a search request
use loc_api::simple_builders::ApiClient;
use loc_api::param_models::FacetReq;
use loc_api::attribute_models::AttributesSelect;
use loc_api::attribute_models::SortField;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = ApiClient::new();
let response = client.search(
"baseball",
false,
Some(AttributesSelect {
include: vec!["pagination".to_string(), "results".to_string()],
exclude: vec![],
}),
Some(FacetReq { filters: vec!["subject:sports".to_string()] }),
Some(25),
Some(1),
Some(SortField::DateDesc),
)?;
println!("url: {}", response.1);
// Handle the search results
if let Some(results) = response.0.results {
for item in results {
println!("{:#?}", item);
}
}
Ok(())
}
Modules
endpoints
LOC API endpoints, providing enums and methods to construct URLs based on different endpoints and parameters.
param_models
Contains structures representing query parameters applicable to multiple endpoints, such as CommonParams
, SearchParams
, ItemParams
, and ResourceParams
.
attribute_models
Defines the possible attributes for query parameters that can be used in API requests, including structures like AttributesSelect
and enums for sorting fields.
format_models
Represents the possible response formats (JSON
or YAML
) and specific media types for endpoints like audio
, books
, maps
, etc.
response_models
Structures that model the responses from LOC API endpoints, such as SearchResultResponse
, ItemResponse
, FormatResponse
, and others.
simple_builders
Provides a high-level ApiClient
for interacting with the LOC API, abstracting endpoint construction, parameter management, and HTTP requests.
Other Projects
- cdg_api: A Rust library for interacting with the Congress.gov API.
License
This project is licensed under the MIT License. See the LICENSE file for more details.
Repository
Dependencies
~4–19MB
~226K SLoC