API Surface Sync

Define typed Python operations once and expose them as SDK, CLI, REST, and MCP surfaces.

The core idea is simple: keep behavior in one canonical operation registry, then let every public surface bind to that registry instead of hand-maintaining parallel implementations.

frompydanticimportBaseModelfromapi_surface_syncimportOperationRegistryregistry=OperationRegistry()
classEchoRequest(BaseModel):
text: strclassEchoResponse(BaseModel):
text: str@registry.operation("echo", request_model=EchoRequest, response_model=EchoResponse)defecho(request: EchoRequest) ->EchoResponse:
returnEchoResponse(text=request.text)

From the same registry:

fromapi_surface_syncimportOperationClientfromapi_surface_syncimportexport_openapifromapi_surface_sync.surfaces.fastapiimportadd_routesfromapi_surface_sync.surfaces.mcpimportadd_toolsfromapi_surface_sync.surfaces.typerimportadd_commands

What This Is For

• Python projects with a real internal API that must appear as multiple surfaces.
• Tools that need SDK, CLI, REST, and MCP parity.
• Projects where OpenAPI is useful, but not the natural source of truth.

What Stays Generic

• Operation registration
• Pydantic request and response contracts
• Surface adapters
• Schema export
• Context/auth hooks as the project evolves

Project-specific concepts belong in the consuming project, not in this library.

Install

pip install "api-surface-sync @ git+https://github.com/ofekron/api-surface-sync.git"

After a PyPI release:

pip install api-surface-sync

For local development:

pip install -e ".[dev]"
pytest

SDK Languages

export_openapi(registry, title="My API") emits an OpenAPI 3.1 contract. Use that contract with OpenAPI Generator, Speakeasy, Stainless, Fern, or custom templates to generate TypeScript, Go, Rust, Java, Swift, or other SDKs from the same operation source.

Status

Early extraction-stage project. The first target consumer is TestApe, but the public contract must remain useful for the common case: one typed Python operation model exposed through several standard API surfaces.