Open Congress API — Philippine Congress data as a graph
A REST API serving Philippine Congress data from Neo4j — legislators, bills, committees, and the relationships between them — with schema validation and self-documenting OpenAPI, built for the BetterGov.ph civic-tech initiative.
Deno / Hono / Neo4j / TypeScript / Zod / OpenAPI / Swagger / Scalar
Context
Philippine Congress data is public but hostile to use: scattered across poorly-structured sources, with relationships — who authored which bill, who sits on which committee, what happened to a measure across sessions — implied rather than queryable. BetterGov.ph wanted an API that civic developers, journalists, and researchers could actually build on.
Constraints
- The domain is a graph, full stop. Bills have multiple authors; authors sit on committees; committees chair bills; bills reference bills. Forcing that into relational tables buys joins and loses the questions people actually ask.
- Civic-tech consumers range from experienced developers to journalism students. The API has to explain itself.
- Volunteer-maintained: boring, standard choices beat clever ones.
Decisions
Neo4j as the primary store, matching the domain's shape. When the data is a graph, the database being a graph removes an entire layer of translation. Traversals that would be three joins are one hop, and the queries read like the questions.
Hono on Deno. Small, fast, typed, and it stays out of the way — the API's value is the data model, not the framework. One runtime from edge to script.
Validate at the edge with Zod. Every response passes through a schema before it ships. Consumers get a stable contract; maintainers get runtime guarantees that the graph hasn't leaked an internal shape.
Documentation is generated, or it's wrong. OpenAPI spec with Swagger and Scalar UI, generated from the same source of truth as the routes. A civic API whose docs drift from its behavior is worse than no API.
What shipped
A public, documented REST API at open-congress-api.bettergov.ph serving legislators, bills, and committees — with the relationships between them as first-class endpoints — under the BetterGov.ph umbrella. The kind of small, solid public infrastructure that makes other civic projects possible.
What I'd do differently
Pagination and caching deserve earlier, more deliberate design for datasets this scrapeable — ETags per resource would make polite crawlers cheaper to run. And the data pipeline (how sources land in the graph) should be as documented as the API itself, since sustainability of civic tech lives or dies on the boring ingest path.