Creating Endpoints

facebook/creating_endpoints

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

2k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

6956

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/facebook/sapling --skill CREATING_ENDPOINTS

The instruction itself

23 sections, as written by the author

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:

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

Key Files Reference

| Component | Location |

|-----------|----------|

| Types | fbcode/eden/scm/lib/edenapi/types/src/ |

| Server Handler Trait | fbcode/eden/mononoke/servers/slapi/slapi_service/src/handlers/handler.rs |

| Server Handlers | fbcode/eden/mononoke/servers/slapi/slapi_service/src/handlers/*.rs |

| Router Registration | fbcode/eden/mononoke/servers/slapi/slapi_service/src/handlers.rs |

| Client API Trait | fbcode/eden/scm/lib/edenapi/trait/src/api.rs |

| Client Implementation | fbcode/eden/scm/lib/edenapi/src/client.rs |

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;
    const API_METHOD: SaplingRemoteApiMethod = SaplingRemoteApiMethod::MyNewMethod;
    const ENDPOINT: &'static str = "/my/endpoint";  // Without /:repo prefix

    async fn handler(
        ectx: SaplingRemoteApiContext<Self::PathExtractor, Self::QueryStringExtractor, Repo>,
        request: Self::Request,
    ) -> HandlerResult<'async_trait, Self::Response> {
        let repo = ectx.repo();
        // ... implementation
    }
}

Hg vs Git Support

By default, handlers only support Hg clients (SUPPORTED_FLAVOURS defaults to [SlapiCommitIdentityScheme::Hg]). Most new endpoints should be Hg-only.

> ⚠️ Avoid adding new Git SLAPI methods. Git support requires additional work in the location service and is discouraged for new endpoints. If you need Git support, consult with the team first.

Non-streaming Pattern

For single-response endpoints, use stream::once:

async fn handler(
    ectx: SaplingRemoteApiContext<Self::PathExtractor, Self::QueryStringExtractor, Repo>,
    request: Self::Request,
) -> HandlerResult<'async_trait, Self::Response> {
    let repo = ectx.repo();

    Ok(stream::once(async move {
        // Do work...
        let result = do_something(&repo, &request).await?;
        Ok(MyResponse { data: result })
    }).boxed())
}

See EphemeralPrepareHandler at handlers/commit.rs:862-892.

Streaming Pattern

For endpoints returning multiple items, use stream::iter or try_stream!:

async fn handler(
    ectx: SaplingRemoteApiContext<Self::PathExtractor, Self::QueryStringExtractor, Repo>,
    request: Self::Request,
) -> HandlerResult<'async_trait, Self::Response> {
    let repo = ectx.repo();

    let results = fetch_multiple_items(&repo, request.items).await?;

    let responses = results
        .into_iter()
        .map(|item| Ok(MyResponse { data: item }));

    Ok(stream::iter(responses).boxed())
}

See CommitMutationsHandler at handlers/commit.rs:1117-1152.

2c. Register the Handler

In handlers.rs, add to build_router():

pub fn build_router<R: Send + Sync + Clone + 'static>(ctx: ServerContext<R>) -> Router {
    // ...
    gotham_build_router(chain, pipelines, |route| {
        // ... existing handlers
        Handlers::setup::<MyNewHandler>(route);
    })
}

Step 3: Add Client-Side Implementation

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

> ⚠️ IMPORTANT: Do not land client-side changes until the server-side diff has been deployed. The server must be available first, otherwise clients will call an endpoint that doesn't exist yet.

3a. Add Endpoint Path

In src/client.rs, add to mod paths:

pub mod paths {
    // ... existing paths
    pub const MY_ENDPOINT: &str = "my/endpoint";
}

3b. Add Trait Method

In trait/src/api.rs, add the method signature to SaplingRemoteApi:

#[async_trait]
pub trait SaplingRemoteApi: Send + Sync + 'static {
    // ... existing methods

    async fn my_endpoint(
        &self,
        request: MyRequest,
    ) -> Result<MyResponse, SaplingRemoteApiError> {
        let _ = request;
        Err(SaplingRemoteApiError::NotSupported)
    }
}

3c. Implement in Client

In src/client.rs, add the implementation:

Non-streaming (single response)

async fn my_endpoint_attempt(
    &self,
    request: MyRequest,
) -> Result<MyResponse, SaplingRemoteApiError> {
    tracing::info!("Calling my_endpoint");
    self.request_single(paths::MY_ENDPOINT, request).await
}

// In impl SaplingRemoteApi for Client:
async fn my_endpoint(
    &self,
    request: MyRequest,
) -> Result<MyResponse, SaplingRemoteApiError> {
    self.with_retry(|this| this.my_endpoint_attempt(request.clone()).boxed())
        .await
}

See ephemeral_prepare_attempt and its trait impl at client.rs:828-850 and 1931-1941.

Streaming (multiple responses)

async fn my_endpoint(
    &self,
    items: Vec<ItemId>,
) -> Result<Vec<MyResponse>, SaplingRemoteApiError> {
    tracing::info!("Requesting {} items", items.len());

    let requests = self.prepare_requests(
        None,
        paths::MY_ENDPOINT,
        items,
        self.config().max_items_per_batch,  // or Some(N) for fixed batch size
        None,
        |items| {
            let req = MyRequest { items };
            self.log_request(&req, "my_endpoint");
            req
        },
        |url, _keys| url.clone(),
    )?;

    self.fetch_vec_with_retry::<MyResponse>(requests).await
}

See commit_mutations at client.rs:1980-2001.

Landing Order

First diff: Server-side changes (types + handler + registration)
Land and wait for deployment

Second diff: Client-side changes
Do not land until server-side is deployed
Once server is deployed, land the client diff

Optional: Query String Parameters

If your endpoint needs query parameters (rarely needed, prefer putting params in request body), define a custom extractor:

#[derive(Debug, Deserialize, StateData, StaticResponseExtender)]
pub struct MyQueryString {
    pub bubble_id: Option<NonZeroU64>,
}

impl SaplingRemoteApiHandler for MyHandler {
    type QueryStringExtractor = MyQueryString;
    // ...

    async fn handler(
        ectx: SaplingRemoteApiContext<Self::PathExtractor, Self::QueryStringExtractor, Repo>,
        request: Self::Request,
    ) -> HandlerResult<'async_trait, Self::Response> {
        let query = ectx.query();
        let bubble_id = query.bubble_id;
        // ...
    }
}

See UploadBonsaiChangesetQueryString at handlers/commit.rs:151-153.

Testing

Server-side unit tests can be added alongside handler code
Integration tests are in fbcode/eden/mononoke/tests/integration/
Client-side tests typically use mock servers or eagerepo

How to use it

Copy the folder

Take facebook/creating_endpoints from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.