HackMD Rust API Client

A Rust client library for the HackMD API.

You can sign up for an account at hackmd.io, and then create access tokens for your projects by following the HackMD API documentation.

Features

✅ Complete API coverage (User, Notes, Teams)
✅ Async/await support with tokio
✅ Automatic retry with exponential backoff
✅ Rate limiting handling
✅ Comprehensive error handling
✅ Type-safe request/response models
✅ Configurable timeouts and retry policies

Installation

Add this to your Cargo.toml:

[dependencies]
hackmd-api-client-rs = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Quick Start

use hackmd_api_client_rs::{ApiClient, ApiClientOptions};
use hackmd_api_client_rs::types::CreateNoteOptions;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create API client
    let client = ApiClient::new(
        "your_access_token_here",
        None, // Use default API endpoint
        Some(ApiClientOptions::default()),
    )?;

    // Get user information
    let user = client.get_me().await?;
    println!("User: {} ({})", user.name, user.email.unwrap_or_default());

    // Create a new note
    let note_options = CreateNoteOptions {
        title: Some("My First Note".to_string()),
        content: Some("# Hello World\\n\\nThis is my first note!".to_string()),
        read_permission: None,
        write_permission: None,
        comment_permission: None,
        permalink: None,
    };

    let note = client.create_note(&note_options).await?;
    println!("Created note: {} (ID: {})", note.note.title, note.note.id);

    Ok(())
}

Configuration

You can customize the client behavior with ApiClientOptions:

use hackmd_api_client_rs::{ApiClient, ApiClientOptions, RetryConfig};
use std::time::Duration;

let options = ApiClientOptions {
    wrap_response_errors: true, // Convert HTTP errors to custom error types
    timeout: Some(Duration::from_secs(30)), // Request timeout
    retry_config: Some(RetryConfig {
        max_retries: 3,
        base_delay: Duration::from_millis(100),
    }),
};

let client = ApiClient::new("your_token", None, Some(options))?;

API Methods

User API

get_me() - Get current user information
get_history() - Get user's note history
get_note_list() - Get user's notes
get_note(note_id) - Get a specific note
create_note(options) - Create a new note
update_note(note_id, options) - Update a note
update_note_content(note_id, content) - Update note content only
delete_note(note_id) - Delete a note

Team API

get_teams() - Get user's teams
get_team_notes(team_path) - Get team's notes
create_team_note(team_path, options) - Create a team note
update_team_note(team_path, note_id, options) - Update a team note
update_team_note_content(team_path, note_id, content) - Update team note content
delete_team_note(team_path, note_id) - Delete a team note

Error Handling

The client provides comprehensive error handling with custom error types:

use hackmd_api_client_rs::error::ApiError;

match client.get_me().await {
    Ok(user) => println!("User: {}", user.name),
    Err(ApiError::TooManyRequests(err)) => {
        println!("Rate limited: {}/{} requests remaining",
                err.user_remaining, err.user_limit);
    },
    Err(ApiError::InternalServer(err)) => {
        println!("Server error: {}", err.message);
    },
    Err(err) => println!("Other error: {}", err),
}

Examples

Run the basic usage example:

cargo run --example basic_usage

Make sure to set your HackMD access token in the example code before running.

Types

All API types are available in the types module:

User - User information
Team - Team information
Note - Note metadata
SingleNote - Note with content
CreateNoteOptions - Options for creating notes
UpdateNoteOptions - Options for updating notes
Various enums for permissions and visibility

License

MIT License

hackmd-api-client-rs 0.1.0