Repository navigation
Spec Developer Experience
Part of the Technical Specification. Requirement prefix: DX.
At https://api.viafrei.de/docs, published with every release (Development Process).
| Section | Content |
|---|---|
| Getting started | Obtain a sandbox key, make a first call with curl, read attribution |
| Concepts | Locations, the envelope, attribution and licences, errors, paging, caching and 304, limits and tiers, languages, time and units, versioning |
| Reference | Every operation, rendered from the OpenAPI document, with executed examples |
| Problem types | One page per type at /problems/<type>
|
| Guides | Route briefing in an app, polling efficiently with ETag, displaying attribution correctly, handling 429
|
| Changelog and deprecations | The release notes and the operation inventory (LCY-013) |
| Terms of use | The API terms and the licence obligations passed to clients |
| ID | Requirement | Verification |
|---|---|---|
| DX-001 | A sandbox instance with fixture data MUST answer the same interface as production with vf_test_ keys, so that a developer can make a first successful call within 10 minutes (QAS-INT-01). |
Ops |
| DX-002 | Sandbox data MUST be synthetic or licence-clean and MUST be labelled as test data in meta.warnings[] (code sandbox). |
Contract |
| DX-003 | Every example in the documentation MUST be executed against the sandbox fixtures in CI. | Docs |
| ID | Requirement | Verification |
|---|---|---|
| DX-010 | The project MUST NOT hand-write client libraries for v1. Clients are generated from the published OpenAPI document; the documentation MUST list generators known to handle the document, with a tested example for at least two languages. | Docs |
| DX-011 | The OpenAPI document MUST be generator-friendly: unique operation ids, named component schemas, no anonymous inline objects in responses beyond the envelope, open enumerations marked (ENV-050). | Lint |
| DX-012 | Should official SDKs be added later, they MUST be generated, versioned with the API release, and tested against the sandbox. | Review |
| ID | Requirement | Verification |
|---|---|---|
| DX-020 | A public status page MUST show the current state per endpoint class, incidents and planned maintenance, and an incident history of at least 90 days. It MUST be hosted independently of the API's own instance. | Ops |
| DX-021 | Status updates MUST follow the timing in OPS-005. | Ops |
The plans and their names are an open owner decision (Project Status). The table states design targets for each tier; a written SLA for a paid plan is issued only when the plan exists.
| Tier | Intended for | Availability target | Support channel | First response target | Covered hours |
|---|---|---|---|---|---|
bulk |
batch and research use | best effort (shed first) | public issues | best effort | none |
standard |
applications | 99.5 % per 30 days (NFR-AVAIL-001) | 2 working days | working days, 09:00–17:00 Europe/Berlin | |
critical |
operational and fleet use | 99.5 % per 30 days with priority under load | e-mail with a priority address | 4 working hours | working days, 08:00–20:00 Europe/Berlin |
Service credits, if any, are defined in the plan's contract, not in this specification.
| ID | Requirement | Verification |
|---|---|---|
| DX-030 | Support channels and targets MUST be published per plan before keys of that plan are issued. | Docs |
| DX-031 | Security reports MUST use private vulnerability reporting, never the support channels (SSC-016). | Docs |
| DX-032 | Breaking changes and deprecations MUST be announced to every active key holder by e-mail at the start of the notice period. | 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