facebook-api-rs

A Rust client library for the Facebook Graph API v23.0, with full support for both native and WebAssembly (WASM) environments.

Features

✅ Facebook Graph API v23.0 - Latest version with 2-year support guarantee
🦀 Rust & WASM - Works in both backend servers and frontend browsers
🔐 OAuth Flow - Complete manual login flow implementation
📄 Pages API - Manage Facebook pages, posts, photos, and videos
📸 Instagram Business API - Access Instagram business accounts, media, and hashtags
🔄 Batch Requests - Optimize API calls with batch operations
⚡ Async/Await - Modern asynchronous Rust patterns
🎯 Type-Safe - Strongly-typed API responses with serde
🔧 Flexible HTTP - Choose between reqwest (default) or web-sys for HTTP

Requirements

Rust 1.81.0 or later
A Facebook App with App ID and App Secret (Create one here)
Valid Facebook access tokens for API calls

Documentation

Installation

Add this to your Cargo.toml:

[dependencies]
facebook_api_rs = "0.1.2"

Or install via cargo:

cargo add facebook_api_rs

Alternative: Install from Git

You can also install directly from GitHub:

[dependencies]
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs" }

Or specify a particular branch, tag, or commit:

[dependencies]
# Use main branch
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs", branch = "main" }

# Use specific tag
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs", tag = "v0.1.0" }

# Use specific commit
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs", rev = "abc123" }

Feature Flags

The crate provides two HTTP client implementations:

reqwest (default) - Uses reqwest for native and WASM targets
web-sys - Uses web-sys for browser-based WASM applications

Using the Default Feature (reqwest)

[dependencies]
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs" }

Using web-sys for WASM

[dependencies]
facebook_api_rs = { git = "https://github.com/osain-az/facebook-api-rs", default-features = false, features = ["web-sys"] }

Quick Start

1. Build a Login URL

Generate a Facebook OAuth login URL to authenticate users:

use facebook_api_rs::prelude::{Config, LoginResponseType, LoginUrlParameters};

fn create_login_url() -> String {
    let config = Config::new(
        "YOUR_APP_ID".to_string(),
        "https://yourapp.com/callback".to_string()
    );

    LoginUrlParameters::new(config)
        .add_response_type(LoginResponseType::TOKEN)
        .add_scope(vec!["email", "public_profile"])
        .full_login_url()
}

2. Handle OAuth Callback

After users authenticate, extract tokens from the redirect URL:

use facebook_api_rs::prelude::UserToken;

async fn handle_callback(redirect_url: String) -> Result<(), Box<dyn std::error::Error>> {
    let tokens = UserToken::extract_user_tokens(redirect_url);

    if let Some(error) = tokens.login_error {
        eprintln!("Login error: {:?}", error);
        return Err(Box::new(error));
    }

    println!("Access token: {}", tokens.access_token);
    Ok(())
}

3. Make API Calls

Use the client to interact with Facebook Graph API:

use facebook_api_rs::prelude::{Client, TokenLiveType};

async fn get_user_pages(user_token: UserToken) -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(user_token, String::new());

    let accounts = client
        .accounts(TokenLiveType::LONGLIVE)
        .get()
        .await?;

    for account in accounts.data {
        println!("Page: {} (ID: {})", account.name, account.id);
    }

    Ok(())
}

API Version Configuration

By default, this crate uses Facebook Graph API v23.0. You can specify a custom version if needed:

use facebook_api_rs::prelude::{Config, Client, UserToken};

// Using default v23.0
let config = Config::new(
    "your_app_id".to_string(),
    "redirect_uri".to_string()
);

// Using custom version (format: vXX.X)
let config = Config::new_with_version(
    "your_app_id".to_string(),
    "redirect_uri".to_string(),
    "v22.0".to_string()
);

// Client with custom version
let client = Client::new_with_version(
    UserToken::default(),
    "page_token".to_string(),
    "v22.0".to_string()
);

Note: Facebook guarantees each API version for at least 2 years. Always use the latest stable version when possible.

Usage Examples

Manual Login Flow

Step 1: Generate Login URL

Build the Facebook OAuth login URL (can be done on frontend or backend):

use facebook_api_rs::prelude::{Config, LoginResponseType, LoginUrlParameters};

```rust
use facebook_api_rs::prelude::{Config, LoginResponseType, LoginUrlParameters};

fn build_login_url() -> String {
    let config = Config::new(
        "YOUR_APP_ID".to_string(),
        "https://yourapp.com/callback".to_string()
    );

    // Use TOKEN response type to get access token directly
    let response_type = LoginResponseType::TOKEN;

    // Or use CODE to exchange for token on server
    // let response_type = LoginResponseType::CODE;

    LoginUrlParameters::new(config)
        .add_response_type(response_type)
        .add_scope(vec!["email", "public_profile", "pages_manage_posts"])
        .full_login_url()
}

Step 2: Handle Login Response

After successful login, extract tokens or handle errors:

use facebook_api_rs::prelude::{Client, Me, TokenLiveType, UserToken};

async fn handle_login_response(redirect_url: String) -> Result<(), Box<dyn std::error::Error>> {
    let tokens = UserToken::extract_user_tokens(redirect_url);

    // Check for login errors
    if let Some(error) = tokens.login_error {
        eprintln!("Login failed: {:?}", error);
        return Err(Box::new(error));
    }

    // If using CODE response type, exchange it for access token
    if !tokens.code.is_empty() {
        // Send code to server for token exchange
        println!("Authorization code: {}", tokens.code);
    }

    // If using TOKEN response type, verify the access token
    if !tokens.access_token.is_empty() {
        // Get user information
        let client = Client::new(tokens.clone(), String::new());
        let user: Me = client
            .accounts(TokenLiveType::LONGLIVE)
            .user()
            .await?;

        println!("User ID: {}", user.id);
        println!("User Name: {}", user.name.unwrap_or_default());
    }

    Ok(())
}

Step 3: Server-Side Token Verification

Verify access tokens or exchange authorization codes on your server:

use facebook_api_rs::prelude::{Config, UserToken};

// Verify an access token
async fn verify_access_token(
    access_token: String,
    user_id: String,
    app_id: String
) -> Result<bool, Box<dyn std::error::Error>> {
    // Use a valid app token or admin token for verification
    let app_token = "YOUR_APP_TOKEN";

    let token_info = UserToken::access_token_information(
        app_token,
        &access_token
    ).await?;

    // Validate token properties
    if !token_info.is_valid {
        return Ok(false);
    }
    if token_info.app_id != app_id {
        return Ok(false);
    }
    if token_info.user_id != user_id {
        return Ok(false);
    }

    Ok(true)
}

// Exchange authorization code for access token
async fn exchange_code_for_token(
    code: String
) -> Result<UserToken, Box<dyn std::error::Error>> {
    let config = Config::new(
        "YOUR_APP_ID".to_string(),
        "https://yourapp.com/callback".to_string()
    );

    let token = UserToken::default()
        .exchange_code_for_access_token_at_server(
            code,
            "YOUR_APP_SECRET".to_string(),
            config
        )
        .await?;

    Ok(token)
}

Working with Facebook Pages

Get user's pages and manage page content:

use facebook_api_rs::prelude::{Client, TokenLiveType};

async fn get_user_pages(user_token: UserToken) -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(user_token, String::new());

    // Get all pages the user manages
    let accounts = client
        .accounts(TokenLiveType::LONGLIVE)
        .get()
        .await?;

    for account in accounts.data {
        println!("Page: {} (ID: {})", account.name, account.id);
        println!("Access Token: {}", account.access_token);
        println!("Category: {}", account.category);
    }

    Ok(())
}

Publishing to Facebook Pages

Create posts, upload photos, and publish videos:

use facebook_api_rs::prelude::{Client, TokenLiveType};

async fn publish_page_post(
    user_token: UserToken,
    page_token: String
) -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(user_token, page_token);

    // Publish a text post
    let result = client
        .pages("PAGE_ID".to_string(), TokenLiveType::LONGLIVE)
        .feed()
        .publish_message("Hello from Rust! 🦀".to_string())
        .await?;

    println!("Post ID: {}", result.id);

    Ok(())
}

Instagram Business API

Access Instagram business accounts and media:

use facebook_api_rs::prelude::{Client, TokenLiveType};

async fn get_instagram_media(
    user_token: UserToken,
    page_token: String
) -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(user_token, page_token);

    // Get Instagram account media
    let media = client
        .instagram_account("INSTAGRAM_BUSINESS_ACCOUNT_ID".to_string())
        .media()
        .fields(vec!["id", "caption", "media_type", "media_url", "timestamp"])
        .get()
        .await?;

    for item in media.data {
        println!("Media ID: {}", item.id);
    }

    Ok(())
}

API Coverage

This crate currently supports:

Authentication & Tokens

✅ OAuth login flow with customizable scopes
✅ Authorization code exchange
✅ Access token verification
✅ Short-lived and long-lived tokens
✅ Token inspection and debugging

User & Accounts API

✅ Get user profile information
✅ List user's managed pages
✅ Page access token management

Facebook Pages API

✅ Publish posts to pages
✅ Upload photos to pages
✅ Upload videos to pages
✅ Page feed management
✅ Search functionality

Instagram Business API

✅ Instagram Business Account access
✅ Media publishing and management
✅ Hashtag search
✅ Media insights

Other Features

✅ Batch API requests
✅ Custom API version support
✅ Error handling with typed errors

Roadmap (v0.1.x)

OAuth login dialog and redirect URL handling
Login response parsing
Authorization code exchange for access tokens
JSON response handling
Access token inspection
Token storage and login status tracking
Canceled login handling
Identity confirmation
Permission checking
Re-requesting declined permissions
User logout functionality
App uninstall detection
User data deletion request handling

Error Handling

The crate uses strongly-typed errors through the ClientErr enum:

use facebook_api_rs::prelude::{Client, ClientErr};

async fn handle_api_errors() {
    match some_api_call().await {
        Ok(data) => println!("Success: {:?}", data),
        Err(ClientErr::HttpError(e)) => eprintln!("HTTP error: {}", e),
        Err(ClientErr::ParseError(e)) => eprintln!("Parse error: {}", e),
        Err(e) => eprintln!("Other error: {:?}", e),
    }
}

Examples

Check out the examples directory for more detailed usage examples, including:

Complete OAuth flow implementation
Instagram integration
Page management

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

# Clone the repository
git clone https://github.com/osain-az/facebook-api-rs.git
cd facebook-api-rs

# Run tests
cargo test

# Build documentation
cargo doc --open

# Run examples (requires Facebook App credentials)
cargo run --example seed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Facebook for Developers - Official API documentation
Built with ❤️ using Rust

Support

Publishing to Crates.io

This crate is ready for publication to crates.io. When published, users will be able to install it with:

[dependencies]
facebook_api_rs = "0.1.0"

To publish (for maintainers):

# Ensure all tests pass
cargo test

# Check the package
cargo package

# Publish to crates.io
cargo publish

Related Projects

facebook-graph-api - Alternative Facebook API client
social-media-api - Multi-platform social media API

Note: This is an unofficial library and is not affiliated with Meta Platforms, Inc.

facebook_api_rs 0.1.2

facebook-api-rs

Features

Requirements

Documentation

Installation

Alternative: Install from Git

Feature Flags

Using the Default Feature (reqwest)

Using web-sys for WASM

Quick Start

1. Build a Login URL

2. Handle OAuth Callback

3. Make API Calls

API Version Configuration

Usage Examples

Manual Login Flow

Step 1: Generate Login URL

Step 2: Handle Login Response

Step 3: Server-Side Token Verification

Working with Facebook Pages

Publishing to Facebook Pages

Instagram Business API

API Coverage

Authentication & Tokens

User & Accounts API

Facebook Pages API

Instagram Business API

Other Features

Roadmap (v0.1.x)

Error Handling

Examples

Contributing

Development Setup

License

Acknowledgments

Support

Publishing to Crates.io

Related Projects