Overview

Introduction to the RC API Client for Rust

The RcApiClient is a Rust client library for interacting with the Recurse Center API. It provides a type-safe, ergonomic interface for accessing profiles, batches, locations, hub visits, and other RC data.

Installation

Add the client to your Cargo.toml:

[dependencies]
reqwest = { version = "0.11", features = ["blocking", "json"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
base64 = "0.21"
chrono = "0.4"
thiserror = "1.0"
urlencoding = "2.1"

Basic Usage

Bearer Token

use rc_api::{RcApiClient, ProfileSearchParams};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with bearer token
    let client = RcApiClient::new("your_access_token".to_string())?;
    
    // Search for profiles
    let profiles = client.search_profiles(ProfileSearchParams {
        limit: Some(50),
        ..Default::default()
    })?;
    
    println!("Found {} profiles", profiles.len());
    Ok(())
}

Client Architecture

The API client is built on top of reqwest and provides:

• Type-safe requests: All API responses are deserialized into strongly-typed structs
• Flexible authentication: Support for both bearer tokens and basic auth
• Automatic URL building: Constructs API URLs from the base URL and version
• Error handling: Custom error types for common API errors
• Blocking interface: Uses reqwest::blocking for synchronous operations

Base URL Configuration

By default, the client uses https://www.recurse.com/api/v1 as the base URL. You can override this for testing:

src/rc_api.rs:9-10,378-410

const BASE_URL: &str = "https://www.recurse.com";
const API_VERSION: &str = "v1";

impl RcApiClient {
    /// Create a new API client with bearer token authentication
    pub fn new(access_token: String) -> Result<Self> {
        Self::with_auth(Authentication::Bearer(access_token))
    }

    /// Create a new API client with basic authentication
    pub fn with_basic_auth(email: String, password: String) -> Result<Self> {
        Self::with_auth(Authentication::Basic { email, password })
    }

    /// Create a new API client with custom authentication
    pub fn with_auth(auth: Authentication) -> Result<Self> {
        let client = Client::builder().user_agent("rc-vcf/0.1.0").build()?;

        Ok(Self {
            client,
            auth,
            base_url: BASE_URL.to_string(),
        })
    }

    /// Set a custom base URL (useful for testing)
    pub fn with_base_url(mut self, base_url: String) -> Self {
        self.base_url = base_url;
        self
    }

    fn build_url(&self, path: &str) -> String {
        format!("{}/api/{}{}", self.base_url, API_VERSION, path)
    }
}

Custom Base URL Example

let client = RcApiClient::new("token".to_string())?
    .with_base_url("https://test.recurse.com".to_string());

Client Struct

RcApiClient · struct

The main API client structure.

Show Fields

client · reqwest::blocking::Client

The underlying HTTP client with user agent “rc-vcf/0.1.0”

auth · Authentication

Authentication method (Bearer or Basic)

base_url · String

Base URL for API requests (default: “https://www.recurse.com”)

Constructor Methods

new · fn(String) -> Result<RcApiClient>

Creates a new API client with bearer token authentication.

Parameters:

• access_token (String): Your RC personal access token

Returns: Result<RcApiClient, RcApiError>

with_basic_auth · fn(String, String) -> Result<RcApiClient>

Creates a new API client with basic authentication.

Parameters:

• email (String): Your RC email address
• password (String): Your RC password

Returns: Result<RcApiClient, RcApiError>

with_auth · fn(Authentication) -> Result<RcApiClient>

Creates a new API client with custom authentication.

Parameters:

• auth (Authentication): Custom authentication enum

Returns: Result<RcApiClient, RcApiError>

with_base_url · fn(self, String) -> RcApiClient

Sets a custom base URL for the client (useful for testing).

Parameters:

• base_url (String): Custom base URL (e.g., “https://test.recurse.com”)

Returns: RcApiClient (consumes self)

Real-World Example

Here’s how the RC VCF Generator uses the client:

src/main.rs:323-333

let auth = rc_api::Authentication::Bearer(
    std::env::var("RECURSE_PAT").expect("RECURSE_PAT environment variable not set"),
);
let client = rc_api::RcApiClient::with_auth(auth).expect("Failed to create API client");

let http_client = Client::builder()
    .user_agent("rc-vcf/0.1.0")
    .build()
    .expect("Failed to create HTTP client");

Next Steps

Authentication

Learn about authentication methods

Profiles API

Search and retrieve RC profiles

Error Handling

Handle API errors gracefully

Batches

Work with RC batches