Skip to content

Spec Developer Experience

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Developer Experience

Part of the Technical Specification. Requirement prefix: DX.

1. Documentation portal

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

2. Sandbox and test keys

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

3. SDK policy

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

4. Status page

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

5. Support and service levels per tier

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) e-mail 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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally