Skip to content

Technical Specification

mavrovde edited this page Nov 1, 2026 · 3 revisions

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).

Reading order

  1. Scope, Conventions and References, then Protocol and Common Envelope.
  2. Resource Model and the endpoint pages for the domain you need; the Data Model for the logical entities behind them.
  3. Errors, Authentication and Authorisation, Rate Limiting, Quotas and Priority.
  4. The quality, delivery and operations pages as your role needs them.

Document map

Interface

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]] —

Data model

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]] —

Quality

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

Delivery and operations

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]] —

Testing (informative, elaborates TST and TEST)

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 mapping

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

Context (C4 level 1)

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
Loading

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.

Informative guides

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.

Requirement ID scheme

<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.

Changes to earlier design pages

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

Open questions for the owner

  1. Approve the safe query POST for long routes (ADR-0005), or keep GET only and cap route length lower.
  2. Approve 422 instead of 409 for ambiguous places (ADR-0003).
  3. Approve UTC instants with …Local companions (ADR-0004).
  4. Route briefing by origin and destination without a road would need a routing engine, which is a non-goal; confirm.
  5. The address of the sandbox instance and the status page.
  6. Plan names, quotas and per-tier support targets; the SLO of 99.5 % on a single host first.
  7. The signed-off licence matrix per source family and use class (LIC-009).

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally