Personal project / 02
Railzway APIs
A personal contract-first API experiment for exploring how public billing and payment interfaces can remain consistent, versioned, and implementation-independent.
01 / Overview
Overview
Railzway APIs contains the canonical Protocol Buffer contracts for Railzway public APIs. It is an engineering experiment in expressing billing, usage ingestion, invoicing, and payment semantics independently from service implementations while exposing the same contract through gRPC and REST/JSON.
02 / Architecture
Architecture flow
03 / Problem
Problem
Public financial APIs need to evolve while preserving compatibility and precise domain behavior. Monetary precision, event replay, effective-dated resources, immutable invoices, payment retries, and tenant boundaries all need semantics that are visible in the contract rather than hidden inside an implementation.
04 / Technical decisions
Technical decisions
- Protocol Buffers as the canonical, versioned source of API contracts
- Resource-oriented standard methods with explicit custom methods for domain actions such as invoice finalization
- gRPC and REST/JSON transcoding from one contract to avoid maintaining parallel API definitions
- Canonical decimal strings and shared Money types instead of binary floating-point values
- Buf linting and breaking-change detection as automated contract quality gates
- Generated clients treated as disposable build artifacts rather than hand-maintained source code
05 / Challenges
Challenges
- Encoding financial and lifecycle invariants clearly at the API boundary
- Keeping organization scoping secure without exposing unnecessary tenant identifiers in public URLs
- Distinguishing technical payment failures from ambiguous or business-level failures
- Designing additive evolution rules that preserve existing consumers
06 / What I learned
What I learned
- API contracts are part of the domain model, not merely transport schemas
- Idempotency and immutability need explicit wire-level semantics
- Breaking-change automation makes contract evolution a repeatable engineering practice
- A shared contract can support multiple transports without coupling it to persistence models