← Back to selected work

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

01Proto contract
02Buf validation
03Generated SDK
04gRPC service
05REST gateway
06API consumer

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