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 by following the developer portal.

Features

• ✅ Complete API coverage (User, Notes, Teams)
• ✅ Async/await support with tokio
• ✅ Retry mechanism with exponential backoff
• ✅ Comprehensive error handling & Type-safe request/response

Installation

cargo add hackmd-api-client-rs

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>",
        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, RetryOptions};
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_options: Some(RetryOptions {
        max_retries: 3,
        base_delay: Duration::from_millis(100),
    }),
};

let client = ApiClient::new("<YOUR_ACCESS_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

[!NOTE] Make sure to set your HackMD access token in the example code before running.

advanced usage example:

cargo run --example advanced_usage

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