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.
The Go implementation (ADR-0001) runs these jobs in .github/workflows/ci.yml on every pull request and push to main; every job is bounded by a timeout and nothing is retried (TST-017):
| Job | What it checks |
|---|---|
| Lint | golangci-lint (with gosec, errorlint, depguard), actionlint with shellcheck |
| Unit and handler tests | go test -race -shuffle=on -coverpkg=./... |
| Integration tests (PostGIS) | the store, the read role and cancellation against a throwaway PostGIS container (testcontainers) |
| Coverage gate (100 % per package) | the unit, integration and boot-smoke profiles merged; any package below 100 % fails (TST-001) |
| Generated files are current | sqlc code, the configuration reference and the OpenAPI document |
| OpenAPI lint and breaking changes | Spectral and oasdiff against the base |
| govulncheck | reachable vulnerabilities in the module and the standard library |
| Image | Hadolint, the multi-architecture build, /healthz of the built image, Trivy |
| Compose smoke | the local stack with Schemathesis against the running API |
| SonarCloud analysis | quality gate over the merged coverage profile |
| Requirement report | every automated MUST row in the milestone's scope has a passing test ([[Testing Strategy |
.github/workflows/security.yml runs on every pull request, on main and weekly: CodeQL, gitleaks over the history, Snyk, dependency review, a dependency-licence check, and an OWASP ZAP API scan against the compose stack. CI adds govulncheck, and the Image job Hadolint and Trivy on the built image. One tool per kind of check: a second tool reporting the same class of finding is not run. Every scanner that can write SARIF uploads it to code scanning; the tools and thresholds are on Spec: Secure SDLC and Supply Chain. Scorecard runs on main and weekly. A job that needs a secret the run does not have fails and names the secret. Releases: Release Process; the image: Container and Deployment.
| 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 (Trivy) | every pull request and every release; fails on high or critical findings |
| OpenSSF Scorecard | weekly |
| Private vulnerability reporting | always available to reporters |
The flow as implemented is on Release Process.
-
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, at https://mavrovde.github.io/viafrei-api/: the release workflow'spagesjob builds the site from the tag (scripts/docs-build.sh) and reads it back until it serves that version. Today the site holds the guide (the README and the configuration, container and security-check pages) and the OpenAPI reference, rendered by Redocly into one self-contained page (no script is loaded from elsewhere when it is read); the getting-started and concept pages above join it as they are written. - Examples are executed in CI against fixtures; the configuration reference is generated from code.
Nightly: long fuzzing runs, the full benchmark, deep Schemathesis runs, load, soak and chaos scenarios on the test stack. Weekly: the full DAST scan, stress and spike runs, scheduled dependency scans and Scorecard. A nightly or weekly failure opens or updates an issue and blocks the next release until resolved.
The testing approach is the Testing Strategy; each milestone has entry and exit criteria on the Test Plan; the gate per stage is on Test Environments and Quality Gates. In short:
- tests are written with the change, carry the requirement IDs they verify and are shown to fail before the fix (TST-003, TST-013);
- tests never reach a live data source or production, and use only the synthetic fixture set (Test Data Management);
- every gate fails closed and prints what it checked; no test is retried to green, flaky tests are quarantined with an issue;
- defects follow Defect Management, and each release publishes a test completion report.
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