oai-pmh

Rust library for the Open Archives Initiative Protocol for Metadata Harvesting.

The immediate need and focus is for a client only. A repository may come later.

Usage

The standard practice will be to:

• Create a client passing in the OAI endpoint
• Create query args as necessary
• Run the query

Examples use the #[tokio::main] macro to create the async runtime. The tokio dependency is not provided by this library therefore you must include it in your Cargo.toml like: tokio = { version = "1", features = ["rt-multi-thread", "macros"] }. For async runtime requirements refer to the reqwest documentation.

use oai_pmh::{Client, ListRecordsArgs, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::new("https://demo.archivesspace.org/oai")?;

    let response = client.identify().await?;
    println!("{:?}", response.payload);

    let args = ListRecordsArgs::new("oai_dc");
    let mut stream = client.list_records(args).await?;
    if let Some(response) = stream.try_next().await? {
        println!("{:?}", response);
    }

    Ok(())
}

Queries that support resumption tokens return an async stream, as in client.list_records in the example.

Custom Request Headers

Use add_header to pass additional HTTP headers with every request, for example when an endpoint requires authentication:

use oai_pmh::{Client, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let mut client = Client::new("https://demo.archivesspace.org/oai")?;
    client.add_header("Authorization", "Bearer abc123")?;

    let response = client.identify().await?;
    println!("{:?}", response.payload);

    Ok(())
}

Custom headers override the defaults (Accept and User-Agent) if the same header name is supplied.

Metadata

To provide flexibilty metadata is not parsed by this library. The OAI response metadata element/s are captured as strings. The expectation is you "bring your own parser" to handle whatever metadata format is supported by the server and requested via the client.

Runnable Examples

List identifiers:

# Use defaults (test.archivesspace.org, oai_ead, 5 responses/pages)
cargo run --example list_identifiers

# Specify endpoint and metadata prefix
cargo run --example list_identifiers https://test.archivesspace.org oai_ead

# Specify number of respones/pages to fetch
cargo run --example list_identifiers https://test.archivesspace.org oai_ead 100

# Specify a different endpoint and metadata format
cargo run --example list_identifiers https://demo.archivesspace.org/oai oai_dc 5

# Basic profiling
cargo build --release --example list_identifiers
/usr/bin/time -v cargo run --example list_identifiers -- https://test.archivesspace.org/oai oai_ead 200

Other examples include:

• List formats and sets
• List records