Repository navigation
Spec Non Functional Requirements
Part of the Technical Specification. Requirement prefixes: NFR-PERF, NFR-AVAIL, NFR-CAP, NFR-SIZE, NFR-FRESH, NFR-SCALE, NFR-RES, NFR-OBS, NFR-SEC, NFR-PRIV, NFR-A11Y, NFR-I18N, NFR-MAINT, NFR-PORT, NFR-TEST. Quality scenarios that make these testable: Spec: Quality Scenarios.
Every figure on this page is a DESIGN TARGET or an ASSUMPTION, not a measurement. There is no running API. Targets are asserted by tests on fixtures and, after release, checked against production telemetry.
The p95 and p99 columns are the budgets of Performance and Caching, grouped into classes; p50 is added here. Latency is measured at the service boundary, from the first request byte read to the last response byte written, for successful (2xx/304) responses, excluding client network time.
| Endpoint class | Operations | p50 | p95 | p99 | Hard deadline |
|---|---|---|---|---|---|
| Conditional hit | any 304
|
5 ms | 10 ms | 30 ms | 2 s |
| Lookup | place search, get by id, describe, addresses, stop search, meta, sources | 40 ms | 120 ms | 300 ms | 2 s |
| Near and motorway | conditions in an area, motorway conditions, roadworks ahead, fuel, charging, parking and sharing near a point, points of interest, weather risk (near and along) | 60 ms | 200 ms | 500 ms | 2 s |
| Live transit | departures, disruptions, accessibility | 80 ms | 250 ms | 600 ms | 2 s |
| Along | fuel, charging and parking along a corridor | 120 ms | 400 ms | 900 ms | 2 s |
| Composed | route briefing, place overview | 300 ms | 800 ms | 1 500 ms | 2 s |
| History | one page of condition history | 150 ms | 400 ms | 1 000 ms | 2 s |
| ID | Requirement | Verification |
|---|---|---|
| NFR-PERF-001 | No request MUST run longer than the hard deadline of 2 s (deadline.request, bounded at 2 s by configuration validation), measured from the first header byte; queueing spends from it. |
Load |
| NFR-PERF-002 | When the deadline is reached, the in-flight storage query MUST be cancelled on the storage side, not merely abandoned; the storage backend MUST be idle within db.cancel_grace plus 100 ms. |
Load |
| NFR-PERF-003 | Each endpoint class MUST meet its p95 and p99 targets above on the benchmark fixtures at the design load (NFR-CAP-001). | Load |
| NFR-PERF-004 | No operation MUST cause a sequential scan of time-series data; query plans MUST be asserted by tests. | Load |
| NFR-PERF-005 | Repeated identical polls MUST be answered with 304 or from the result cache at a rate of at least 95 % on the benchmark's polling scenario. |
Load |
| NFR-PERF-006 | Under 50 concurrent identical requests, exactly one storage read MUST occur (single-flight). | Load |
| ID | Requirement | Verification |
|---|---|---|
| NFR-AVAIL-001 |
Availability SLO (design target): 99.5 % of valid requests in a rolling 30-day window MUST be answered without a 5xx status. Valid means: authenticated, within limits, well-formed. 429 and 4xx are not failures; 503 deadline-exhausted and upstream-unavailable are. |
Ops |
| NFR-AVAIL-002 | Error budget: 0.5 % of valid requests per 30 days, about 216 minutes of full unavailability. The budget policy on [[Spec: Operations | Spec-Operations]] applies when it is spent. |
| NFR-AVAIL-003 | Latency SLO (design target): 99 % of valid requests in 30 days MUST complete within their class's p99 target. | Ops |
| NFR-AVAIL-004 | Planned maintenance MUST NOT cause unavailability: deployments MUST be rolling or blue-green with connection draining (server.shutdown_grace). |
Ops |
| NFR-AVAIL-005 | The SLO MUST be reviewed after the first 90 days of production telemetry; until then it is provisional. Per-tier SLAs are on [[Spec: Developer Experience | Spec-Developer-Experience]]. |
| ID | Requirement | Verification |
|---|---|---|
| NFR-CAP-001 | Assumption A-CAP-1: the design load of one instance is 50 requests per second sustained and 200 per second for 10 s bursts, with the request mix of the benchmark. The service MUST meet NFR-PERF-003 at this load with the design resource limits. | Load |
| NFR-CAP-002 | The service MUST hold its share of storage connections at or below db.pool_max and its role's connection limit at all loads, so that it can never starve other readers of the shared store. |
Load |
| NFR-CAP-003 | Above capacity, throughput MUST stay flat (no collapse): excess requests are refused with 429 within 50 ms, not queued until they time out. |
Load |
| Limit | Design default | Key |
|---|---|---|
| Request URI | 8 KiB | server.max_uri_bytes |
| Request header fields | 16 KiB | server.max_header_bytes |
| Query body | 64 KiB | server.max_body_bytes |
| Route points | 2 000 | geo.max_route_points |
| Route length | 1 500 km | geo.max_route_km |
| Page size | default 50, max 500 (and the plan's max) |
pagination.default_limit, pagination.max_limit
|
| Geometry vertices per feature | 5 000 | geo.max_vertices |
| Uncompressed response body | 8 MiB | http.max_response_bytes |
| ID | Requirement | Verification |
|---|---|---|
| NFR-SIZE-001 | Every limit above MUST be enforced before work is done, and MUST be a configuration key with bounds. | Config |
| NFR-SIZE-002 | A response that would exceed http.max_response_bytes MUST be cut at a page boundary with hasMore: true, never truncated mid-document. |
Handler |
The API does not make data fresher than storage holds it; it reports age and flags staleness. Stale thresholds are design targets per family category:
| Category | Stale after (design target) | Key |
|---|---|---|
| Road situations | 15 min | freshness.stale_after.roads |
| Fuel prices | 30 min | freshness.stale_after.fuel |
| Charging availability | 30 min | freshness.stale_after.charging |
| Parking occupancy | 30 min | freshness.stale_after.parking |
| Real-time departures | 5 min | freshness.stale_after.departures |
| Facility states | 60 min | freshness.stale_after.accessibility |
| Weather warnings | 30 min | freshness.stale_after.weather |
| Places and rules | 45 days | freshness.stale_after.places |
| ID | Requirement | Verification |
|---|---|---|
| NFR-FRESH-001 | Every data response MUST report per family dataAsOf, ageS and stale (ENV-003). |
Contract |
| NFR-FRESH-002 | When any contributing family is stale, the response MUST carry the data_stale warning; it MUST still answer. |
Handler |
| NFR-FRESH-003 |
Cache-Control max-age MUST NOT exceed the family's stale threshold. |
Config |
| NFR-FRESH-004 | Freshness versions MUST be read lazily, at most every cache.freshness_poll, and only while traffic exists. |
Unit |
| ID | Requirement | Verification |
|---|---|---|
| NFR-SCALE-001 | The request path MUST be stateless apart from caches and limiter state; any instance MUST be able to answer any request. | Review |
| NFR-SCALE-002 | Horizontal scale-out MUST require only configuration: shared limiter state, a central connection pooler and read replicas are additions, not rewrites ([[Architecture Overview | Architecture-Overview]]). |
| NFR-SCALE-003 | With several instances, per-key limits MUST either use shared state or be divided by the instance count (ratelimit.instances), and the documentation MUST say which applies. |
Config |
| ID | Requirement | Verification |
|---|---|---|
| NFR-RES-001 | Every outbound wait MUST be bounded: storage connect (db.connect_timeout), statement (remaining budget), access-store write (metering.write_timeout). No unbounded wait MAY exist. |
Lint |
| NFR-RES-002 | A circuit breaker MUST protect storage: after breaker.failure_threshold consecutive failures within breaker.window, it opens for breaker.open_for and answers 503 upstream-unavailable at once; then it admits breaker.half_open_probes trial requests. |
Unit |
| NFR-RES-003 | Composed features MUST degrade per part (FR-BRIEF-004, FR-BRIEF-005) and flag it in meta.parts and the partial warning. |
Handler |
| NFR-RES-004 | While storage is unavailable, a cached response no older than cache.stale_if_error MAY be served with the served_stale warning; otherwise 503. |
Handler |
| NFR-RES-005 | Failure of the access store MUST NOT stop serving keys already in the key cache; metering MUST buffer up to metering.max_keys_buffered and drop with a metric beyond it. |
Unit |
| NFR-RES-006 | On shutdown, the service MUST stop accepting, drain in-flight requests within server.shutdown_grace, flush metering, then exit. |
Handler |
| NFR-RES-007 | A storage connection MUST be returned to the pool only if verifiably idle; otherwise it MUST be discarded. | Load |
| NFR-RES-008 | The service MUST never retry a storage read within a request; retries belong to the client. | Review |
| ID | Requirement | Verification |
|---|---|---|
| NFR-OBS-001 | RED metrics MUST be exported per operation and tier: request Rate, Errors by status and problem type, Duration histograms; plus admission queue depth and wait, shed counts, storage in-flight and duration by named query, cache hits, 304 count, licence-gate violations, unknown storage codes. |
Handler |
| NFR-OBS-002 | The metrics endpoint MUST be reachable only on loopback or an operator network, never on the public listener. | Security |
| NFR-OBS-003 | One structured access log line per request MUST record: request id, client correlation id, key id (public part only), tier, operation id, status, problem type, total, queue and storage time, cache outcome, response bytes, trace id. | Unit |
| NFR-OBS-004 | Logs MUST NOT contain keys, secrets, request bodies, full query strings, storage statement parameters or full client addresses; addresses MUST be truncated to log.ip_prefix bits (IPv4) and log.ip6_prefix bits (IPv6). A test MUST plant secrets and search every sink. |
Security |
| NFR-OBS-005 | Traces MUST follow W3C Trace Context and OpenTelemetry conventions, off by default, parent-based ratio sampling (otel.sample_ratio); spans name queries by their static name, never by parameters. |
Unit |
| NFR-OBS-006 |
/healthz and /readyz MUST behave as specified in FR-SVC-004. |
Handler |
| NFR-OBS-007 | Every alert MUST link to a runbook ([[Spec: Operations | Spec-Operations]]). |
| ID | Requirement | Verification |
|---|---|---|
| NFR-SEC-001 | Every response MUST carry Strict-Transport-Security: max-age=31536000; includeSubDomains (http.hsts_max_age), X-Content-Type-Options: nosniff, Content-Security-Policy: default-src 'none'; frame-ancestors 'none' (JSON responses), Referrer-Policy: no-referrer and Cross-Origin-Resource-Policy: same-site unless CORS applies. |
Handler |
| NFR-SEC-002 | Every input MUST be validated against the OpenAPI schema (type, format, range, length, pattern, enumeration) before use, with allow-lists rather than deny-lists. | Contract |
| NFR-SEC-003 | Storage access MUST use parameterised statements only; no request value MAY be concatenated into a statement. | Lint |
| NFR-SEC-004 | The service's storage role MUST be read-only, limited to the read contract, with a role-level statement timeout and connection limit (tested). | Security |
| NFR-SEC-005 | The service MUST meet OWASP ASVS 5.0 level 2 for the applicable chapters; deviations are recorded in an ADR. | Security |
| NFR-SEC-006 | The OWASP API Security Top 10 (2023) mapping below MUST be kept current and each control MUST have a test. | Review |
| Risk | Control in this specification |
|---|---|
| API1 Broken object level authorisation | All data is non-personal and shared; ids are opaque; the licence gate decides per family (SEC-030 to SEC-033); no object belongs to a caller |
| API2 Broken authentication | Bearer keys with checksum, MAC at rest, constant-time compare, uniform 401, failure limiting (SEC-001 to SEC-052) |
| API3 Broken object property level authorisation | Response schemas are allow-lists; fields cannot add members; storage names never reach payloads (FR-GEN-003, ENV-032) |
| API4 Unrestricted resource consumption | Size limits, bounded areas and windows, pagination caps, rate limits, quotas, priority admission, 2 s deadline (NFR-SIZE, FR-LOC-006, RATE) |
| API5 Broken function level authorisation | One scope per operation; no administrative function on the public listener (SEC-020, NFR-OBS-002) |
| API6 Unrestricted access to sensitive business flows | Bulk extraction limited by quotas, history depth and windows; no bulk export in v1 |
| API7 Server-side request forgery | The API makes no outbound request based on client input |
| API8 Security misconfiguration | Boot refuses invalid configuration; security headers; TLS policy; no version disclosure (PROT-002, PROT-032, CFG-003) |
| API9 Improper inventory management | One OpenAPI document per major, published; disabled operations vanish from it; deprecation headers; sandbox separate (FR-SVC-005, VER) |
| API10 Unsafe consumption of APIs | The API consumes only its own storage through the read contract, with total mapping tables and the post-check (ENV-051, SEC-032) |
| ID | Requirement | Verification |
|---|---|---|
| NFR-PRIV-001 | The API MUST serve mobility data only; no payload MAY contain personal data of third parties. | Review |
| NFR-PRIV-002 | Full client addresses MUST exist only in memory for the per-IP limiter window (ratelimit.ip_state_ttl) and MUST NOT be written to any store; logs carry truncated prefixes only. |
Security |
| NFR-PRIV-003 | Access logs MUST be deleted after log.retention_days (design 7 days); usage records are aggregates per key, hour and operation, without request contents or addresses, retained per metering.retention_days. |
Ops |
| NFR-PRIV-004 | The API MUST NOT set cookies, use tracking, fingerprinting or third-party analytics. The documentation portal MUST NOT load third-party trackers. | Security |
| NFR-PRIV-005 | Key-holder contact data MUST be limited to what operating the key requires and processed under GDPR Art. 6(1)(b); see [[Spec: Data Governance | Spec-Data-Governance]]. |
| NFR-PRIV-006 | Processing MUST take place in Germany or the EU; no key-holder data MAY be transferred to third countries. | Review |
| ID | Requirement | Verification |
|---|---|---|
| NFR-A11Y-001 | The documentation portal MUST conform to WCAG 2.2 level AA (contrast, keyboard use, headings, text alternatives for diagrams). | Docs |
| NFR-A11Y-002 | Every diagram in the documentation MUST have an equivalent text description. | Docs |
| NFR-I18N-001 | All human-readable texts produced by the service (titles, lamp reasons, problem titles) MUST exist in de and en; a missing translation is a build failure. |
Lint |
| NFR-I18N-002 | Number formats in JSON MUST be locale-independent; localisation applies to text only. | Contract |
| NFR-MAINT-001 | The layering of [[Architecture Overview | Architecture-Overview]] MUST be enforced by the build: the domain imports neither storage nor HTTP code. |
| NFR-MAINT-002 | Every configuration key MUST be declared once with type, default, bounds and description; the published reference MUST be generated from the declaration. | Config |
| NFR-MAINT-003 | Cyclomatic complexity per function SHOULD stay at or below 15; files above 500 lines SHOULD be split. | Lint |
| NFR-PORT-001 | The service MUST run as one OCI container image, as a non-root user, with a read-only root filesystem, configured only by environment and files (Twelve-Factor III), logging to standard output (XI). | Ops |
| NFR-PORT-002 | The image MUST be built for linux/amd64 and linux/arm64. |
Ops |
| NFR-PORT-003 | The service MUST NOT depend on a specific hosting provider's services. | Review |
| NFR-TEST-001 | Every requirement on these pages MUST be traceable to at least one test or review ([[Spec: Traceability Matrix | Spec-Traceability-Matrix]]). |
| NFR-TEST-002 | The service MUST be runnable against a fixture-backed storage stub with no network access, for tests and the sandbox. | Ops |
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