sebuf

README

Build HTTP APIs from protobuf definitions

Transform your protobuf services into production-ready HTTP APIs with automatic documentation and validation.

🚀 Try it in 30 seconds

# Clone and run the working example
git clone https://github.com/SebastienMelki/sebuf.git
cd sebuf/examples/simple-api
make demo

This starts a working HTTP API with JSON endpoints and OpenAPI docs - all generated from a simple .proto file.

What you get

Five generators from one .proto file:

Generator	Output
protoc-gen-go-http	Go HTTP servers with routing, request binding, validation, and error handling
protoc-gen-go-client	Go HTTP clients with type safety, header helpers, and per-call options
protoc-gen-ts-client	TypeScript HTTP clients with type safety, header helpers, and per-call options
protoc-gen-ts-server	TypeScript HTTP servers with routing, request binding, validation, and error handling — runs on Node, Deno, Bun, Cloudflare Workers
protoc-gen-openapiv3	OpenAPI v3.1 specs that stay in sync with your code, one file per service

Validation and error handling — built in, not bolted on:

• Automatic request body validation via buf.validate annotations
• HTTP header validation with type checking and format validation (UUID, email, datetime)
• Structured error responses with field-level details in JSON or protobuf
• Proto messages ending with "Error" automatically implement Go's errors.As() / errors.Is()

Developer experience:

• Mock server generation with realistic field examples for rapid prototyping
• Zero runtime dependencies — works with any Go HTTP framework

How it works

From this protobuf definition:

service UserService {
  // Header validation at service level
  option (sebuf.http.service_headers) = {
    required_headers: [{
      name: "X-API-Key"
      type: "string"
      format: "uuid"
      required: true
    }]
  };
  
  rpc CreateUser(CreateUserRequest) returns (User);
}

message CreateUserRequest {
  // Automatic validation with buf.validate
  string name = 1 [
    (buf.validate.field).string = {
      min_len: 2, max_len: 100
    },
    (sebuf.http.field_examples) = {
      values: ["Alice Johnson", "Bob Smith", "Charlie Davis"]
    }
  ];
  string email = 2 [
    (buf.validate.field).string.email = true,
    (sebuf.http.field_examples) = {
      values: ["alice@example.com", "bob@example.com"]
    }
  ];
  
  oneof auth_method {
    EmailAuth email = 3;
    TokenAuth token = 4;
  }
}

sebuf generates:

Go — handlers, clients, and mocks:

// HTTP handlers with automatic validation (headers + body)
api.RegisterUserServiceServer(userService, api.WithMux(mux))

// Type-safe HTTP client with functional options
client := api.NewUserServiceClient("http://localhost:8080",
    api.WithUserServiceAPIKey("your-api-key"),
)
user, err := client.CreateUser(ctx, req)

// Mock server with realistic data
mockService := api.NewMockUserServiceServer()
api.RegisterUserServiceServer(mockService, api.WithMux(mux))

TypeScript — clients and servers:

// HTTP client with full type safety
const client = new UserServiceClient("http://localhost:8080", {
  apiKey: "your-api-key",
});
const user = await client.createUser({ name: "John", email: "john@example.com" });

// HTTP server (framework-agnostic, Web Fetch API)
const routes = createUserServiceRoutes(handler);
// Wire into any framework: Bun.serve, Deno.serve, Express, Hono, etc.

OpenAPI — validation rules, headers, and examples included automatically:

UserService.openapi.yaml

Quick setup

# Install the tools
go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-go-http@latest
go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-go-client@latest
go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-openapiv3@latest
go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-ts-client@latest
go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-ts-server@latest

# Try the complete example
cd examples/simple-api && make demo

Used in Production

WorldMonitor Real-time global intelligence dashboard tracking seismology, cyber threats, markets, aviation, and more. Full-stack TypeScript with sebuf — generated TS clients, TS server handlers, and OpenAPI docs all from the same proto definitions. Actively battle-testing sebuf across every generator. See the integration PR.	alpaca-go Type-safe Go SDK for the Alpaca Trading API — 100+ endpoints across trading, market data, brokerage, and auth, all generated from protobuf definitions. The entire Alpaca REST API modeled as proto files with sebuf annotations. Clients, validation, and OpenAPI docs that can never drift from the actual API.
Anghami & OSN+ sebuf powers API services at Anghami, the leading music streaming platform in the Middle East and North Africa, and at OSN+, the region's premium streaming service featuring HBO, Paramount+, and OSN Originals.	Sarwa sebuf is used at Sarwa, the fastest-growing investment and personal finance platform in the MENA region, powering type-safe API contracts across their trading, investing, and savings services.

Next steps

• Complete Tutorial - Full walkthrough with working code
• Documentation - Comprehensive guides and API reference
• More Examples - Additional patterns and use cases

Built on Great Tools

sebuf stands on the shoulders of giants, integrating with an incredible ecosystem:

• Protocol Buffers by Google - The foundation for everything
• protovalidate by Buf - Powers our automatic validation
• Buf CLI - Modern protobuf tooling and dependency management
• OpenAPI 3.1 - Industry standard API documentation
• Common Expression Language (CEL) by Google - Flexible validation rules

We're grateful to all maintainers of these projects that make sebuf possible.

Contributing

We welcome contributions! See CONTRIBUTING.md for details.

License

MIT License - see LICENSE

Star History