Repository navigation
Development Process
viafrei-api is developed in the open with the full, normal GitHub process. This page describes how changes are proposed, checked, released and documented.
-
mainis protected. Every change arrives through a pull request. - A pull request needs green required checks and an approving review from a code owner; stale approvals are dismissed when new commits arrive.
- Linear history (squash merges), no force pushes, no branch deletion, conversations resolved before merge.
- Pull-request titles follow Conventional Commits (
feat:,fix:,docs:…), checked automatically, because releases are generated from them. - Issue and pull-request templates ask for the problem, the change, the evidence and the tests.
| Step | Purpose |
|---|---|
| Formatting and dependency hygiene | consistent code; no stray dependencies |
| Linting, scope lint, configuration lint | code quality; nothing about data collection or internal names; no tunable literals |
| Regeneration diff | typed queries, the OpenAPI document and the configuration reference must match the code |
| Tests with a PostGIS service container | unit, mapping, role, cancellation and query-plan tests; coverage gate |
| Fuzz smoke | a short fuzzing run on every parser |
| OpenAPI checks | Spectral lint, oasdiff breaking-change diff against main, executed documentation examples |
| Documentation build | the guide and the reference build cleanly |
| Image build and boot smoke | the container starts, /readyz answers, Schemathesis and a short k6 run pass |
| Vulnerability check | the language's vulnerability scanner over dependencies |
All third-party actions are pinned by commit SHA, and Dependabot updates the pins.
| Tool | When |
|---|---|
| CodeQL | every push and pull request, and weekly |
| Dependency review | every pull request; fails on high severity or a disallowed licence |
| Dependabot | weekly grouped version updates, plus security updates |
| Secret scanning with push protection | always, including a custom pattern for ViaFrei key prefixes |
| Container image scan (Grype) | every release; fails on critical findings |
| OpenSSF Scorecard | weekly |
| Private vulnerability reporting | always available to reporters |
-
release-please reads Conventional Commits on
mainand maintains a release pull request with the changelog. - Merging it creates the semantic-version tag and the GitHub Release.
- The release publishes a multi-architecture container image to the GitHub Container Registry with build provenance, an SBOM and a keyless signature, scanned before publication.
- The API's version is kept in step with the ViaFrei platform's version: a version-sync pull request updates the read-contract file, the parity fixtures and the platform version, and tells release-please which version to cut.
GET /v1/metareports both versions and the contract version. - The platform's deployment check reports a mismatch between the deployed API and the platform's schema.
- A getting-started guide (obtain a key, make a first call), concept pages (attribution, errors, limits, tiers, versioning), a page per error type, and the OpenAPI reference rendered with Scalar.
- Published to GitHub Pages from
mainon every release. - Examples are executed in CI against fixtures; the configuration reference is generated from code.
Long fuzzing runs, the full benchmark and deep Schemathesis runs.
A change is done when its tests, documentation and changelog entry are in the same pull request, every required check is green, a reviewer has approved it, and nothing in it describes how data is collected.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference