README.md

Newswrap

Hacker News API bindings for Rust.

use newswrap::{client::HackerNewsClient, errors::HackerNewsClientError};

#[tokio::main]
async fn main() -> Result<(), HackerNewsClientError> {
    // Build your client at the start of your application process
    let client = HackerNewsClient::new();

    // Call various endpoints with your client instance
    let generic_item = client.items.get_item(69).await?;
    dbg!(&generic_item);

    // Determine what the item type is
    let item_type = generic_item.get_item_type();
    dbg!(item_type);

    // Check if the item is job
    assert!(generic_item.is_story());

    // Retrieve user information
    let user = client.users.get_user("joeymckenzie").await?;
    dbg!(user);

    Ok(())
}

What is newswrap?

Newswrap provides a convenient Rust interface for the Hacker News API. Hacker News is a community-driven website targeted at software developers and technology professionals. While Hacker News offers up its API for the general public, there are no official language-based libraries for connecting to it. This project aims to provide an easy-to-use Rust-based client for retrieving data from Hacker News in an idiomatic fashion with first-class async support.

Using newswrap

To get started with newswrap within your Rust application, simply add the package,

cargo add newswrap

and spin up the client at the start of your application process:

use newswrap::{client::HackerNewsClient, errors::HackerNewsClientError};

#[tokio::main]
async fn main() -> Result<(), HackerNewsClientError> {
    // Build your client at the start of your application process
    let client = HackerNewsClient::new();

    // Check for the latest item ID
    let latest_id = client.realtime.get_latest_item_id().await?;

    // Get the latest stories IDs
    let story = client.items.get_story(69).await?;
    println!("{}... nice.", story.title);

    // Retrieve user profiles and information
    let my_profile = client.users.get_user("joeymckenzie").await?;

    if let Some(about_section) = my_profile.about {
        println!("{}", about_section);
    }

    Ok(())
}

Under the hood, newswrap relies on reqwest for collecting information from the Hacker News API via HTTP. It's advised for consumers of the newswrap client to instantiate a single instance at the start of your application process. Examples are available for using clients in binary applications and web applications (with axum).