Repository navigation
Glossary
mavrovde edited this page Nov 1, 2026
·
3 revisions
Terms used consistently across this wiki. Terms used only in the normative text of the Technical Specification are also defined in Spec: Scope, Conventions and References section 4.
| Term | Meaning |
|---|---|
| Access store | The API's own small store of keys, plans, terms acceptance, audit records and hourly usage. Owned by the API repository. |
| Admission controller | The component that decides, before a database connection is used, whether a request is served now, queued by priority, or refused with 429. |
| ADR (architecture decision record) | A short record of one significant decision: context, options, decision, consequences and status (proposed, accepted, superseded). See [[Spec: Architecture Decision Records |
| Aggregate | A cluster of domain objects treated as one unit, with a root (for example a ChargingSite and its charge points). |
| Anti-corruption layer | The storage adapter that translates between the read contract and the domain model, so storage names never reach the public API. |
| Attribution | The publisher and licence text a source requires to be shown with its data. Carried in meta.attribution on every data response. |
| Bounded context | A part of the domain with its own consistent language, such as Road conditions or Energy stops. |
| Burn rate | How fast the error budget is being consumed, relative to the rate that would use exactly the whole budget in the SLO window. Alerts fire on high burn rates over two windows. |
| C4 model | A way of drawing software architecture at four levels: context, containers, components and code. The specification uses the context and container levels. |
| Canary | A release step in which a new version first serves a small share of traffic and is promoted only if its error and latency figures stay within limits. |
| Composed feature | An endpoint that combines several stores in one answer, such as the route briefing. |
| Condition note / purpose note | A sentence a licence requires to accompany its data, passed on verbatim in meta.notes. |
| Conformance | The state of an implementation that meets every MUST of the specification, verified by the stated methods. See [[Spec: Conformance and Acceptance |
| Contract file | The machine-readable description of the read contract (views, columns, types, code lists, version) that the platform delivers to the API repository. Contains no internal names. |
| Corridor | A stretch of road for "along" questions: a motorway section with direction, or a client route with a buffer. |
| Data dictionary | The alphabetical list of every field and code list of the logical read model. See [[Data Dictionary |
| Deadline | The hard 2 second budget of every request, enforced in the service and in the database. |
| Definition of Done / Definition of Ready | The checklists an item must satisfy before work starts (Ready) and before it counts as finished (Done). See [[Spec: Development Workflow |
| Design target | A goal the implementation must meet and that tests check. Not a measurement. |
| DORA metrics | Four delivery measures: deployment frequency, lead time for changes, change failure rate and time to restore service. |
| DPIA | Data protection impact assessment under GDPR Art. 35, required before high-risk processing of personal data. |
| Error budget | The amount of unreliability an SLO allows in its window, for example 0.5 % of requests over 30 days at 99.5 %. Its policy decides when feature work pauses for reliability work. |
| ETag / 304 | An HTTP validator derived from source freshness; a matching If-None-Match returns 304 Not Modified without database work. |
| Freshness version | A cheap per-source-family version number that changes when the family's data changes. |
| Keyset pagination | Paging by an opaque cursor that encodes the last position, instead of an offset. |
| Logical read model | The entities and fields the API reads, written under neutral names on the [[Data Model |
| Lamp | A green, amber or red summary of conditions for a corridor, area or place. |
| Licence gate | The rule that decides which source families a request may read, from the key's plan, its use class, accepted terms and configuration. |
| Local rendering | The …Local companion of a UTC instant, giving the same instant in Europe/Berlin with its offset, for display to people. |
| MCP server | ViaFrei's Model Context Protocol server, through which AI assistants use the same data. |
| Metering | Counting requests, shed requests, 304 answers and database time per key, hour and feature. |
| Observation | One live state of a thing at one observation instant, kept append-only; the opposite of a current-state record. See [[Data Model |
| Parity | The guarantee, tested on fixtures, that an endpoint answers the same facts as its MCP counterpart for the same input. |
| Part | One component answer inside a composed feature (roads, weather, energy, parking), with its own status, deadline and freshness, reported in meta.parts. |
| Plan | A set of limits, a tier, a use class and the source families a key may use. |
| Port | An interface declared in the domain that a use case calls; implemented by an adapter. |
| Problem details | The RFC 9457 error format, application/problem+json. |
| Quality scenario | A testable statement of a quality attribute: source, stimulus, environment, artefact, response and response measure (ISO/IEC 25010, arc42). |
| Read contract | The published, versioned set of read-only views through which the API reads ViaFrei's data. The only part of the platform the API can see. Its substance is the logical read model. |
| Record envelope | The fields every record of the logical read model carries: its source, its natural key, its timestamps and its soft-close mark. |
| Requirement ID | The stable identifier of one normative statement, such as PROT-041; never reused. See [[Technical Specification |
| Retention class | The temporal rule of an entity: reference (REF), current state (CUR), observation (OBS) or transient (TRN); durations are configuration. |
| Runbook | The written procedure for one alert: impact, diagnosis, mitigation, escalation and verification. |
| Sandbox | An instance with synthetic fixture data that answers the same interface as production, for vf_test_ keys. |
| SBOM | Software bill of materials: the machine-readable list of every component in a build (CycloneDX or SPDX). |
| Scope | A feature family a key may call: places, roads, energy, parking, transit, accessibility, weather, rules, history. |
| Shedding | Refusing lower-priority work early, with Retry-After, so higher-priority work stays fast. |
| Single-flight | Collapsing many identical concurrent requests into one database read. |
| SLI / SLO / SLA | A service level indicator is a measured ratio of good events; an objective is its target over a window; an agreement is a contractual promise to a customer, which may carry credits. |
| SLSA | Supply-chain Levels for Software Artifacts: a framework of build integrity levels with signed provenance. |
| Soft close | Keeping a record its publisher stopped publishing, marked with the instant it was withdrawn, instead of removing it. |
| Source family | A group of sources with the same licence treatment, used by the licence gate and in attribution. |
| STRIDE | A threat classification: spoofing, tampering, repudiation, information disclosure, denial of service and elevation of privilege. |
| Sunset | The date after which a deprecated operation or version stops answering, announced with the Sunset header. |
| Tier | A priority class: critical, standard or bulk. |
| Traceability matrix | The generated table linking every requirement to its page, its verification method and its evidence. See [[Spec: Traceability Matrix |
| Trust boundary | A line in the architecture where data or control passes between parts with different levels of trust; every crossing is authenticated, validated or both. |
| Use class | The kind of use a plan represents: consumer, non-commercial or commercial. Matched against each source's licence. |
| Value object | An immutable domain value defined by its content, such as a Price or a TimeWindow. |
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