Post/standardizing civic apis with protobuf and connectrpc

[mlhamel]

Summary

Adds a new technical deep dive to the blog: "Standardizing Civic Data APIs with Protobuf and ConnectRPC"
(content/blog/standardizing-civic-apis-with-protobuf-and-connectrpc/index.md).

This post explores the architectural design behind the Civican ecosystem, detailing how
taking a contract-first approach with Protocol Buffers and ConnectRPC solves data fragmentation across Canadian
federal parliamentary (LEGISinfo) and lobbying ([Lobby Canada](https://github.
com/civican/lobbycanada)) records.

---

Key Highlights & Topics Covered

1. Contract-First API Architecture (civican-schemas):

   • Centralizing schemas using Protocol Buffers and managing toolchains via Buf.
   • Code generation matrix: Python dataclasses, static type hints (.pyi), ConnectRPC async stubs, and Pydantic
     models for automatic OpenAPI integration.

2. Cross-Domain Schema Composition:

   • Demonstrating how lobbycanada.proto imports legisinfo.proto so CrossReferenceBillResponse embeds typed
     BillDetail entities directly, guaranteeing zero schema drift across separate civic domains.

3. Why ConnectRPC over Traditional gRPC / REST:

   • Multi-protocol support (Connect, gRPC-Web, standard gRPC).
   • Native browser compatibility (fetch) and curl-friendly JSON endpoints without needing an Envoy proxy.

4. Service Implementation (civican-server):

   • ASGI / FastAPI mounting with ConnectASGIWrapper.
   • Reader abstraction pattern decoupling storage/DuckDB engines from RPC servicers.
   • Dynamic service discovery and unified OpenAPI schema generation.

5. Data Repositories as Ephemeral Consumers:

   • How pure data repositories (civican/lobbycanada, civican/legisinfo) remain free of duplicate API server
     boilerplate.
   • Running the standardized ConnectRPC API on-the-fly via make run using uv run --with "civican-server @ ..."
     against local DuckDB databases.

---

Changed Files

• content/blog/standardizing-civic-apis-with-protobuf-and-connectrpc/index.md: Full technical article with diagrams,
  .proto snippets, and Makefile recipes.

---

Verification

• Ran zola build — compiled cleanly (0 warnings, 0 broken links).
• Checked syntax highlighting for code blocks (proto, yaml, python, makefile, bash).
• Verified local rendering on desktop and mobile viewports.