Skip to content

Principles

mavrovde edited this page Nov 1, 2026 · 1 revision

Principles

These are the promises the ViaFrei API makes. Each one is backed by a concrete design mechanism and, where possible, by an automated test that fails if the promise is broken.

1. Data licences and attribution are law

ViaFrei's data comes from many publishers under different licences: open licences that require attribution, share-alike licences, and terms that restrict use to consumer information or require explicit acceptance.

Promise How it is kept
Every answer says who published the data and under which licence A meta.attribution block in every data response, plus a Link: …; rel="license" header pointing to the public source register
Condition and purpose notes are passed on word for word meta.notes.condition and meta.notes.purpose carry the licence's required sentences verbatim
A key never receives data its plan may not receive The licence gate decides, per request, which source families a key may read; the allowed set is passed into the database query, so forbidden rows are never read
Defence in depth Every returned row is checked again against the allowed set; a violation is an error and an alert, never a silent leak
Default deny A source family is enabled for a plan only after its licence has been reviewed; until then the gate refuses it
Share-alike data stays share-alike Such answers carry their condition note and a pointer to the corresponding share-alike export

The public source register is available at GET /v1/sources. See Security and Access Keys for how plans and use classes interact with the gate.

2. Privacy

  • The API serves mobility data, not personal data.
  • API keys are never stored in plain text and never written to logs. Logs carry only the public key id.
  • Client IP addresses in logs are truncated to a network prefix.
  • Keys in URLs are refused (400 key-in-query), because URLs end up in logs and browser histories.
  • Usage metering records counts per key, hour and feature, not request contents.
  • Hosting is in Germany, and no third-party key-management or gateway service holds key-holder data.

3. Security

  • Read-only database access through a dedicated role that cannot write and cannot see beyond the read contract (tested).
  • Keys with high entropy, a checksum, a visible prefix for secret scanning, expiry, rotation with an overlap window, and immediate revocation.
  • Strict input validation and size limits on every parameter; bounded areas, windows and page sizes.
  • Signed, scanned container images with provenance and an SBOM; dependency scanning on every pull request.
  • Private vulnerability reporting on the repository.

Details: Security and Access Keys and Development Process.

4. Reliability: the 2 second rule

  • Hard deadline: no request runs longer than 2 seconds. The budget starts when the request arrives; queueing spends from it.
  • The database stops too: when a request's time is up, its query is cancelled inside PostgreSQL, not merely abandoned by the client.
  • Fail fast: if a request cannot be served in time, it is refused at once with a clear error and a Retry-After hint, instead of waiting and failing late.
  • Partial answers are honest: a composed answer (for example a route briefing) reports the status of each part (ok, timeout, not_permitted, unavailable) instead of failing completely.
  • Good neighbour: the API has a hard cap on its share of the shared database, so it can never starve the MCP server or the website.

Details: Rate Limits and Priority.

5. Transparency

  • This design is public before the code.
  • The OpenAPI 3.1 document is generated from the code, committed, linted and diffed for breaking changes on every pull request.
  • Every documented example is executed against test fixtures in CI, so the documentation cannot drift from behaviour.
  • GET /v1/meta reports the API version, the platform version and the read-contract version it was built against.
  • Every configuration key is documented with its default and bounds, generated from the code.

6. Open process

Public pull requests, required reviews, public CI, CodeQL, dependency review, OpenSSF Scorecard, automated releases with changelogs, and published documentation. See Development Process.

7. Honesty about status

We label design targets as targets and assumptions as assumptions. We do not publish numbers we have not measured on the thing being described.

8. Germany-wide rules

Every behaviour is one national rule applied the same way everywhere. There are no special cases for one city or one region in the API's logic.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally