Creating EdenAPI Endpoints

This guide explains how to create new EdenAPI/SLAPI endpoints, covering both streaming and non-streaming patterns.

Overview

EdenAPI is a REST-like API that connects Sapling clients to the Mononoke server. Creating a new endpoint involves three main steps:

1. Define Types - Request and response types in edenapi_types
2. Server Handler - Implement the handler in slapi_service
3. Client Implementation - Add client-side code (lands after server)

Key Files Reference

Step 1: Define Request/Response Types

Location: fbcode/eden/scm/lib/edenapi/types/src/

Types need the #[auto_wire] macro to generate wire format serialization and the ToWire trait implementation. All parameters should be sent in the request body, not in the URL path.

Required Attributes

#[auto_wire]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[derive(Serialize, Deserialize)]
#[cfg_attr(any(test, feature = "for-tests"), derive(Arbitrary))]
pub struct MyRequest {
    #[id(1)]
    pub field_one: String,
    #[id(2)]
    pub field_two: Option<u64>,
}

Key points:

• #[auto_wire] generates wire format code
• #[id(N)] assigns a stable field ID for serialization (use sequential numbers)
• Include Serialize, Deserialize for serde support
• Arbitrary derive enables property-based testing
• All parameters go in the request struct, not in URL path

Non-streaming Example

See EphemeralPrepareRequest/EphemeralPrepareResponse in types/src/commit.rs:555-570:

#[auto_wire]
#[derive(Clone, Default, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub struct EphemeralPrepareRequest {
    #[id(1)]
    pub custom_duration_secs: Option<u64>,
    #[id(2)]
    pub labels: Option<Vec<String>>,
}

// Response doesn't need #[auto_wire] if not batched
#[derive(Clone, Debug, Deserialize, Serialize, Eq, PartialEq)]
pub struct EphemeralPrepareResponse {
    pub bubble_id: NonZeroU64,
    pub expiration_timestamp: Option<i64>,
}

Streaming Example

See CommitMutationsRequest/CommitMutationsResponse in types/src/commit.rs:609-623:

#[auto_wire]
#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize)]
pub struct CommitMutationsRequest {
    #[id(1)]
    pub commits: Vec<HgId>,
}

#[auto_wire]
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct CommitMutationsResponse {
    #[id(1)]
    pub mutation: HgMutationEntryContent,
}

Step 2: Create Server-Side Handler

Location: fbcode/eden/mononoke/servers/slapi/slapi_service/src/handlers/

2a. Add Method to SaplingRemoteApiMethod Enum

In handlers.rs, add your method to the enum:

pub enum SaplingRemoteApiMethod {
    // ... existing methods
    MyNewMethod,
}

And update the Display impl:

impl fmt::Display for SaplingRemoteApiMethod {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let name = match self {
            // ... existing matches
            Self::MyNewMethod => "my_new_method",
        };
        write!(f, "{}", name)
    }
}

2b. Implement the Handler

Create a handler struct and implement SaplingRemoteApiHandler:

pub struct MyNewHandler;

#[async_trait]
impl SaplingRemoteApiHandler for MyNewHandler {
    type Request = MyRequest;
    type Response = MyResponse;

    const HTTP_METHOD: hyper::Method = hyper::Method::POST;

…