Repository navigation
Spec Endpoints Service
Part of the Technical Specification. Requirement prefix: FR-SVC. These operations, except the presenting key (section 5), need no key, are not metered against a quota, and are subject to the per-IP limit only (RATE-001).
GET /v1/sources · operationId listSources
The public attribution and terms register: every source family the API can serve, whether or not the caller's plan includes it.
{
"data": [
{
"family": "roads.federal",
"domain": "roads",
"publisher": "Example federal road authority",
"attributionText": "Data: Example federal road authority, DL-DE BY 2.0",
"licence": "Datenlizenz Deutschland – Namensnennung – Version 2.0",
"licenceId": "DL-DE-BY-2.0",
"licenceUrl": "https://www.govdata.de/dl-de/by-2-0",
"shareAlike": false,
"shareAlikeExport": null,
"conditionNotes": [],
"purposeNotes": [],
"termsAcceptanceRequired": false,
"useClasses": ["consumer", "non_commercial", "commercial"],
"freshnessTargetS": 900
}
],
"meta": { "generatedAt": "2026-11-01T13:05:00Z", "registerVersion": "2026-11-01" }
}GET /v1/sources/{family} returns one entry. Each entry's fragment https://api.viafrei.de/v1/sources#<family> is the target of Link: rel="license" headers.
GET /v1/meta · operationId getMeta
{
"data": {
"apiVersion": "1.4.0",
"platformVersion": "2.6.0",
"contractVersion": "3.2",
"openapi": "https://api.viafrei.de/v1/openapi.json",
"languages": ["de", "en"],
"deprecations": [],
"termsOfUse": "https://viafrei.de/…",
"status": "https://api.viafrei.de/status"
}
}Version numbers in the example are placeholders.
| Path | Meaning | Answer |
|---|---|---|
/healthz |
Liveness: the process runs and its event handling is responsive. Never touches storage. |
200 {"status":"ok"} or no answer |
/readyz |
Readiness: both storage connections answer within health.ready_timeout, the read contract is compatible, the access store is migrated |
200 {"status":"ready"} or 503 {"status":"not_ready","checks":{"storage":"fail"}}
|
Health answers are unversioned, MUST NOT carry versions, hostnames, addresses or error text, and carry Cache-Control: no-store.
| Path | Content |
|---|---|
/v1/openapi.json |
The OpenAPI 3.1 document for v1, application/vnd.oai.openapi+json;version=3.1 with application/json accepted |
/v1/openapi.yaml |
The same document in YAML |
/openapi.json |
302 to the newest stable major's document |
/docs |
The rendered reference and guide ([[Spec: Developer Experience |
/problems/{type} |
One documentation page per problem type ([[Spec: Errors |
GET /v1/key · operationId getKey · needs a key, no scope
The key that made the request: its id, plan, use class, expiry, and the source families the licence gate lets it receive, each with its attribution (Spec: Authentication and Authorisation, Spec: Data Licensing and Attribution). During the last auth.expiry_warning_days before expiry, meta.warnings carries key_expiring. It never returns the secret, the stored MAC or the client address. It answers the refusals of a keyed operation (401 missing-key, invalid-key, key-expired, key-revoked, 429 rate-limited), and 404 feature-disabled on an instance without an access store.
| ID | Requirement | Verification |
|---|---|---|
| FR-SVC-001 |
/v1/sources MUST list every family that any plan can receive, with publisher, attribution text, licence name, identifier and URL, share-alike flag, notes and use classes, and MUST be available without a key. |
Contract |
| FR-SVC-002 | The register MUST be generated from the same register the licence gate reads, so the public list and the gate cannot disagree. | Unit |
| FR-SVC-003 |
/v1/meta MUST report the API version, the platform version and the read-contract version, and MUST contain no secret, hostname or address (tested). |
Security |
| FR-SVC-004 |
/healthz MUST NOT touch storage; /readyz MUST fail when storage, the contract version or the access-store migrations are not ready. |
Handler |
| FR-SVC-005 |
/v1/openapi.json MUST be byte-identical to the committed, released document of the running version, minus operations disabled by configuration (FR-GEN-006). |
Contract |
| FR-SVC-006 | Every problem type URI MUST resolve to a human-readable page. | Docs |
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