https://github.com/eastsun5566/hackmd-api-client-rs
🦀📝 A HackMD Rust API client for rustacean & friends
https://github.com/eastsun5566/hackmd-api-client-rs
api client hackmd mardown sdk
Last synced: 7 months ago
JSON representation
🦀📝 A HackMD Rust API client for rustacean & friends
- Host: GitHub
- URL: https://github.com/eastsun5566/hackmd-api-client-rs
- Owner: EastSun5566
- License: mit
- Created: 2023-08-10T17:40:39.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-26T16:44:23.000Z (9 months ago)
- Last Synced: 2025-06-30T03:17:21.759Z (8 months ago)
- Topics: api, client, hackmd, mardown, sdk
- Language: Rust
- Homepage: https://crates.io/crates/hackmd-api-client-rs
- Size: 30.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HackMD Rust API Client
[](https://crates.io/crates/hackmd-api-client-rs)
[](https://docs.rs/hackmd-api-client-rs)
> 🦀📝 A Rust client library for the [HackMD API](https://hackmd.io/@docs/HackMD_API_Book).
You can sign up for an account at [hackmd.io](https://hackmd.io/), and then create access tokens by following the [developer portal](https://hackmd.io/@hackmd-api/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
```bash
cargo add hackmd-api-client-rs
```
## Quick Start
```rust
use hackmd_api_client_rs::{ApiClient, ApiClientOptions};
use hackmd_api_client_rs::types::CreateNoteOptions;
#[tokio::main]
async fn main() -> Result<(), Box> {
// Create API client
let client = ApiClient::new(
"",
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(¬e_options).await?;
println!("Created note: {} (ID: {})", note.note.title, note.note.id);
Ok(())
}
```
## Configuration
You can customize the client behavior with `ApiClientOptions`:
```rust
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("", 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:
```rust
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:
```bash
cargo run --example basic_usage
```
> [!NOTE]
> Make sure to set your HackMD access token in the example code before running.
advanced usage example:
```bash
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