Repository navigation
Technical Specification
The normative, stack-independent specification of the ViaFrei API at https://api.viafrei.de/v1. It turns the design pages of this wiki into numbered, testable requirements. Where a design page and the specification differ, the specification applies and the design page has been updated to match.
Status: draft for review, revision 1. No implementation exists yet; every figure is a design target or an assumption, never a measurement. The implementation stack is open (ADR-0001, proposed).
- Scope, Conventions and References, then Protocol and Common Envelope.
- Resource Model and the endpoint pages for the domain you need; the Data Model for the logical entities behind them.
- Errors, Authentication and Authorisation, Rate Limiting, Quotas and Priority.
- The quality, delivery and operations pages as your role needs them.
| Page | Prefix | Content |
|---|---|---|
| [[Scope, Conventions and References | Spec-Scope-and-Conventions]] | CONV |
| [[Protocol | Spec-Protocol]] | PROT |
| [[Common Envelope | Spec-Common-Envelope]] | ENV |
| [[Resource Model | Spec-Resource-Model]] | FR-LOC, FR-GEN |
| [[Endpoints, Places | Spec-Endpoints-Places]] | FR-PLACE |
| [[Endpoints, Roads | Spec-Endpoints-Roads]] | FR-ROAD |
| [[Endpoints, Energy and Parking | Spec-Endpoints-Energy-and-Parking]] | FR-ENERGY, FR-PARK |
| [[Endpoints, Public Transport and Accessibility | Spec-Endpoints-Transit-and-Accessibility]] | FR-TRANSIT, FR-ACCESS |
| [[Endpoints, Weather Risk, Driving Rules and Composed Features | Spec-Endpoints-Weather-Rules-and-Composed]] | FR-WEATHER, FR-RULES, FR-BRIEF |
| [[Service Endpoints | Spec-Endpoints-Service]] | FR-SVC |
| [[Errors | Spec-Errors]] | ERR |
| [[Authentication and Authorisation | Spec-Authentication-and-Authorisation]] | SEC |
| [[Rate Limiting, Quotas and Priority | Spec-Rate-Limiting-and-Quotas]] | RATE |
| [[Data Licensing and Attribution | Spec-Data-Licensing-and-Attribution]] | LIC |
| [[Compatibility and Versioning | Spec-Compatibility-and-Versioning]] | VER |
| [[OpenAPI Skeleton | Spec-OpenAPI-Skeleton]] | — |
| Page | Prefix | Content |
|---|---|---|
| [[Data Model | Data-Model]] | DM |
| [[Places | Data-Model-Places]], [[Roads | Data-Model-Roads]], [[Energy |
| [[Mapping | Data-Model-Mapping]] | DM |
| [[Data Dictionary | Data-Dictionary]] | — |
| Page | Prefix | Content |
|---|---|---|
| [[Non-Functional Requirements | Spec-Non-Functional-Requirements]] | NFR-* |
| [[Quality Scenarios | Spec-Quality-Scenarios]] | QAS-* |
| [[Threat Model | Spec-Threat-Model]] | THR, TM |
| [[Configuration Cross-Reference | Spec-Configuration-Cross-Reference]] | CFG |
| Page | Prefix | Content |
|---|---|---|
| [[Architecture Decision Records | Spec-Architecture-Decisions]] | ADR |
| [[Secure SDLC and Supply Chain | Spec-Secure-SDLC-and-Supply-Chain]] | SSC |
| [[Development Workflow | Spec-Development-Workflow]] | DEV |
| [[Test Strategy | Spec-Test-Strategy]] | TST |
| [[Conformance and Acceptance | Spec-Conformance-and-Acceptance]] | TEST |
| [[CI/CD and Release | Spec-CI-CD-and-Release]] | REL |
| [[Operations | Spec-Operations]] | OPS |
| [[Data Governance | Spec-Data-Governance]] | GOV |
| [[API Lifecycle and Governance | Spec-API-Lifecycle-and-Governance]] | LCY |
| [[Developer Experience | Spec-Developer-Experience]] | DX |
| [[Risks, Assumptions and Constraints | Spec-Risks-Assumptions-Constraints]] | CON, ASM, RISK |
| [[Traceability Matrix | Spec-Traceability-Matrix]] | — |
The testing document set follows ISO/IEC/IEEE 29119-3 and uses ISTQB terms. It elaborates the TST and TEST rows above and never overrides them.
| Page | Content |
|---|---|
| [[Testing Strategy | Testing-Strategy]] |
| [[Test Plan | Test-Plan]] |
| [[Test Data Management | Test-Data-Management]] |
| [[Contract and Schema Testing | Contract-and-Schema-Testing]] |
| [[Performance Test Plan | Performance-Test-Plan]] |
| [[Security Test Plan | Security-Test-Plan]] |
| [[Test Environments and Quality Gates | Test-Environments-and-Quality-Gates]] |
| [[Test Documentation Templates | Test-Documentation-Templates]] |
| [[Defect Management | Defect-Management]] |
Terms are defined in the Glossary and, for specification terms, in Scope, Conventions and References section 4.
| arc42 section | Where |
|---|---|
| 1 Introduction and goals | [[Vision and Goals |
| 2 Constraints | [[Risks, Assumptions and Constraints |
| 3 Context and scope | [[Scope, Conventions and References |
| 4 Solution strategy | [[Principles |
| 5 Building block view | [[Architecture Overview |
| 6 Runtime view | [[Protocol |
| 7 Deployment view | [[CI/CD and Release |
| 8 Crosscutting concepts | [[Common Envelope |
| 9 Architecture decisions | [[Architecture Decision Records |
| 10 Quality requirements | [[Non-Functional Requirements |
| 11 Risks and technical debt | [[Risks, Assumptions and Constraints |
| 12 Glossary | [[Glossary |
flowchart LR
C[API client: app, fleet system, research] -->|HTTPS with key| A[ViaFrei API]
A -->|read-only role, read contract| S[(Platform storage, owned by the platform)]
M[MCP server, same facts] --> S
O[Operator] -->|admin on loopback| A
The API reads storage it does not own, through a published read contract; it writes only to its own access store (keys, plans, usage, audit). Container view and trust boundaries: Threat Model.
The specification draws on, without claiming certification against: arc42 (structure), ISO/IEC 25010 (quality model), the C4 model (views), the Twelve-Factor App (configuration and processes), the Google SRE books (SLOs, error budgets, alerting, postmortems), OWASP ASVS and the OWASP API Security Top 10 (security requirements and tests), NIST SP 800-218 SSDF (secure development), SLSA (build provenance), OpenSSF Scorecard (repository hygiene), the Microsoft REST API Guidelines, Google AIPs and the Zalando RESTful API Guidelines (API style), Semantic Versioning, Conventional Commits, Keep a Changelog, and the DORA metrics (delivery performance). Normative references (RFCs and standards) are listed in Scope, Conventions and References section 6.
<PREFIX>-<NNN>, never reused; quality scenarios use QAS-<ATTRIBUTE>-<NN>; decision records use ADR-<NNNN>. Every requirement row names a verification method; the Traceability Matrix is generated from the rows. Details: Scope, Conventions and References section 3.
The specification settled points the design pages had left open or stated differently. The design pages now match:
| Topic | Before | Now | Decision |
|---|---|---|---|
| Ambiguous place | 409 ambiguous-place |
422 ambiguous-place; 409 is not used |
ADR-0003 |
| Instants | rendered in Europe/Berlin with an offset | UTC with Z, plus a …Local field in Europe/Berlin where people read it |
ADR-0004 |
| Methods |
GET, HEAD, OPTIONS
|
plus a safe query POST on long-route operations only |
ADR-0005 |
| Page link | meta.page.next |
meta.page.nextCursor and links.next
|
ENV-020 to ENV-026 |
| Language | Accept-Language |
lang parameter overriding Accept-Language
|
PROT-025 |
- Approve the safe query
POSTfor long routes (ADR-0005), or keepGETonly and cap route length lower. - Approve
422instead of409for ambiguous places (ADR-0003). - Approve UTC instants with
…Localcompanions (ADR-0004). - Route briefing by origin and destination without a road would need a routing engine, which is a non-goal; confirm.
- The address of the sandbox instance and the status page.
- Plan names, quotas and per-tier support targets; the SLO of 99.5 % on a single host first.
- The signed-off licence matrix per source family and use class (LIC-009).
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