Repository navigation
Spec Protocol
mavrovde edited this page Nov 1, 2026
·
1 revision
Part of the Technical Specification. Requirement prefix: PROT. Conventions: Spec: Scope, Conventions and References.
| ID | Requirement | Verification |
|---|---|---|
| PROT-001 | The API MUST be reachable only over HTTPS. Plain HTTP on port 80 MUST answer only with a redirect to HTTPS that carries no data and MUST NOT accept a key; a key presented over plain HTTP MUST be treated as leaked and the operator alerted when it can be identified. | Security |
| PROT-002 | TLS 1.3 MUST be offered; TLS 1.2 MAY be offered with AEAD cipher suites and forward secrecy only. TLS 1.1 and older, SSLv3, RC4, CBC-mode suites and static RSA key exchange MUST NOT be offered. | Security |
| PROT-003 | HTTP/1.1 and HTTP/2 (via ALPN) MUST be supported. HTTP/3 MAY be offered later without a version change. | Ops |
| PROT-004 | The base URL MUST be https://api.viafrei.de (configuration key server.public_base_url), and every versioned operation MUST live under /v{major}, for example /v1/places. |
Contract |
| PROT-005 | Paths MUST be lower case, hyphen-separated nouns; collection names plural. A trailing slash MUST NOT be significant: a path with one trailing slash MUST answer 308 Permanent Redirect to the path without it. |
Handler |
| PROT-006 | The total request URI MUST NOT exceed server.max_uri_bytes (default 8 KiB); a longer one MUST be refused with 414 (uri-too-long). Request header fields together MUST NOT exceed server.max_header_bytes; a larger set MUST be refused with 431. |
Config |
The API is read-only. No operation changes server-side state visible to a client.
| ID | Requirement | Verification |
|---|---|---|
| PROT-010 | Every operation MUST support GET and HEAD. HEAD MUST return the same status and headers as GET, without a body, and MUST count against limits like GET. |
Handler |
| PROT-011 |
OPTIONS MUST be answered without authentication, with an Allow header, and, for a CORS preflight, with the CORS headers of section 6. It MUST NOT count against a key's quota. |
Handler |
| PROT-012 |
POST MUST be accepted only on the operations that declare a query body (route briefing and the "along a route" variants of energy, parking, roads and weather), for routes too long for a URI. Such a POST is a safe, idempotent query in the sense of RFC 9110 section 9.2: it creates nothing, its body uses the same parameter names as the query string, and it MUST be answered exactly as the equivalent GET. |
Handler |
| PROT-013 | Any other method, or POST on an operation without a query body, MUST be answered with 405 (method-not-allowed) and an Allow header listing the permitted methods. |
Handler |
| PROT-014 | Every operation is safe and idempotent; an Idempotency-Key header MUST be ignored. Clients MAY retry any request; see the retry rules in [[Spec: Errors |
Spec-Errors]]. |
| ID | Requirement | Verification |
|---|---|---|
| PROT-020 | The default response media type MUST be application/json. Operations that return located objects MUST also offer application/geo+json (RFC 7946). Errors MUST be application/problem+json. |
Contract |
| PROT-021 | Selection MUST follow Accept with quality values (RFC 9110 section 12.5.1). A request whose Accept admits none of the offered types MUST receive 406 (not-acceptable) listing the available types. A missing Accept or */* selects application/json. |
Handler |
| PROT-022 | The format query parameter (json, geojson) MAY be used instead of Accept and MUST take precedence over it. |
Handler |
| PROT-023 | Every text response MUST be UTF-8 and MUST declare it only where the media type defines a charset parameter. A request body (query POST) MUST be application/json in UTF-8; another media type MUST be refused with 415 (unsupported-media-type); a body above server.max_body_bytes with 413 (payload-too-large). |
Handler |
| PROT-024 | Responses at or above http.compress_min_bytes MUST be compressed when the client accepts it: br and gzip MUST be supported, zstd MAY be. The service MUST NOT compress responses that carry secrets (none do in v1) and MUST NOT compress below the threshold. |
Handler |
| PROT-025 | Response language MUST be selected by the lang query parameter if present, else by Accept-Language using BCP 47 lookup matching (RFC 4647 section 3.4), else de. An unsupported but well-formed tag MUST fall back by lookup, then to de, never to an error. A malformed lang MUST be 400 (invalid-parameter). The chosen language MUST be reported in Content-Language and meta.language. |
Handler |
| PROT-026 | Licence notes passed on verbatim (see [[Spec: Data Licensing and Attribution | Spec-Data-Licensing-and-Attribution]]) MUST NOT be translated in place; the language of each is tagged in the payload. |
| Header | Status | Meaning |
|---|---|---|
Authorization: Bearer <key> |
REQUIRED for keyed operations (or X-API-Key) |
The API key, RFC 6750 syntax |
X-API-Key: <key> |
OPTIONAL alternative | For clients that cannot set Authorization. Presenting both with different values is 400 (invalid-parameter) |
Accept |
OPTIONAL | Media type selection |
Accept-Encoding |
OPTIONAL |
br, gzip, zstd
|
Accept-Language |
OPTIONAL | Text language; lang overrides |
If-None-Match, If-Modified-Since
|
OPTIONAL | Conditional GET
|
If-Match, If-Unmodified-Since
|
OPTIONAL | Evaluated per RFC 9110 section 13.2 |
traceparent, tracestate
|
OPTIONAL | W3C Trace Context |
X-Request-Id |
OPTIONAL | A client correlation token, at most 64 characters of [A-Za-z0-9._-]; recorded as the client id, never used as the server request id |
Origin |
set by browsers | CORS |
User-Agent |
RECOMMENDED | Client name and version, for example fleet-app/2.3 (+https://example.org)
|
| Header | When | Meaning |
|---|---|---|
Content-Type, Content-Language, Content-Encoding
|
always / text / compressed | |
X-Request-Id |
always | The server-generated request id (a time-ordered UUID, RFC 9562 version 7); also in meta.requestId and in every problem body |
ETag, Last-Modified
|
every cacheable 200 and 304
|
See section 5 |
Cache-Control, Vary
|
always | See section 5 |
RateLimit-Policy, RateLimit
|
every keyed response | See [[Spec: Rate Limiting and Quotas |
Retry-After |
every 429 and 503, and 504 where known |
Delay in whole seconds |
Link |
data responses |
rel="license" to the source register, rel="next" for a further page, rel="describedby" to the OpenAPI document, rel="deprecation" and rel="sunset" where applicable (RFC 8288) |
Deprecation, Sunset
|
deprecated operations | RFC 9745, RFC 8594 |
WWW-Authenticate |
every 401
|
Bearer realm="viafrei-api" with error per RFC 6750 section 3 |
Allow |
405, OPTIONS
|
|
Strict-Transport-Security, X-Content-Type-Options, Content-Security-Policy, Referrer-Policy, Cross-Origin-Resource-Policy
|
always | See [[Spec: Non-Functional Requirements |
| ID | Requirement | Verification |
|---|---|---|
| PROT-030 | Every response, including errors and 304, MUST carry X-Request-Id. The id MUST be generated by the service; a client-supplied X-Request-Id MUST be logged as a separate client correlation value only after validation, and MUST NOT be echoed. |
Handler |
| PROT-031 | A valid incoming traceparent MUST be honoured as the parent of the service's trace when tracing is enabled; an invalid one MUST be ignored without error. The service MUST NOT propagate trace context to any third party. |
Unit |
| PROT-032 | Responses MUST NOT carry headers that reveal the implementation (Server version strings, X-Powered-By) or internal timings of storage. |
Security |
| PROT-033 | Unknown request headers MUST be ignored. Unknown query parameters MUST be refused with 400 (invalid-parameter), naming each, so that typos are not silently ignored. |
Handler |
| PROT-034 | A query parameter given more than once MUST be refused with 400, except parameters declared repeatable (for example via). List values MUST be comma-separated (kinds=closure,roadworks). |
Handler |
flowchart TD
R[GET with If-None-Match] --> K[Authenticate key and apply the licence gate]
K --> T[Compute ETag from feature, normalised query,<br/>allowed families, family versions, language]
T --> M{Matches?}
M -->|yes| N[304 Not Modified<br/>no database work, counts against quota]
M -->|no| A[Admission, read, 200 with ETag]
| ID | Requirement | Verification |
|---|---|---|
| PROT-040 | Every cacheable 200 MUST carry a weak entity tag (W/"…") derived from the operation, the normalised query, the set of source families the key may read, the freshness versions of the families read and the response language. Two keys with different permitted families MUST never receive the same entity tag for different bodies. |
Unit |
| PROT-041 |
If-None-Match with a matching tag MUST yield 304 with ETag, Cache-Control, Vary, X-Request-Id and the rate-limit headers, before any storage read and before priority admission. A 304 MUST count against the quota. |
Handler |
| PROT-042 |
If-Modified-Since MUST be evaluated against Last-Modified (the newest data instant among the families read) only when If-None-Match is absent (RFC 9110 section 13.2.2). |
Handler |
| PROT-043 | Because entity tags are weak, If-Match with a tag MUST fail and yield 412 (precondition-failed); If-Match: * and If-Unmodified-Since MUST be evaluated per RFC 9110. |
Handler |
| PROT-044 | A data 200 MUST carry Cache-Control: private, max-age=<n> where n is the configured maximum age of the source family (cache.max_age.<family>); a composed answer MUST use the minimum over its parts. Responses MUST NOT be marked public, because they depend on the key. |
Handler |
| PROT-045 | Responses with status 401, 403, 429, 5xx MUST carry Cache-Control: no-store. 400, 404, 405, 406, 412, 422 MAY carry a short private, max-age. |
Handler |
| PROT-046 | Data responses MUST carry Vary: Authorization, X-API-Key, Accept, Accept-Language, Accept-Encoding, plus Origin when CORS headers are present. |
Handler |
| PROT-047 | A response served while storage is unavailable from a still-held cached copy (see NFR-RES-004) MUST carry meta.warnings[] code served_stale and its true Age. |
Handler |
| ID | Requirement | Verification |
|---|---|---|
| PROT-050 | CORS MUST be disabled unless http.cors.allowed_origins lists origins. Only exact listed origins MUST be echoed in Access-Control-Allow-Origin; * MUST NOT be combined with credentials, and Access-Control-Allow-Credentials MUST NOT be sent (the API uses no cookies). |
Security |
| PROT-051 | A preflight MUST allow the methods GET, HEAD, POST, OPTIONS and the request headers Authorization, X-API-Key, Accept, Accept-Language, If-None-Match, If-Modified-Since, Content-Type, traceparent, tracestate, X-Request-Id, and MUST set Access-Control-Max-Age from http.cors.max_age. |
Handler |
| PROT-052 | Actual responses MUST expose ETag, Last-Modified, Link, RateLimit, RateLimit-Policy, Retry-After, X-Request-Id, Content-Language, Deprecation, Sunset. |
Handler |
| PROT-053 | The documentation MUST warn that a key used from a browser is visible to its user, and SHOULD recommend calling the API from a server. | Docs |
sequenceDiagram
autonumber
participant C as Client
participant S as Service
C->>S: request
S->>S: assign request id and the 2 s deadline
S->>S: syntax limits, method, path, Accept
S->>S: per-IP flood control
S->>S: key, scope, licence gate
S->>S: parameter validation
S->>S: rate limit, then quota
S->>S: conditional request, result cache
S->>S: priority admission
S->>S: read with the remaining budget
S-->>C: response with meta, attribution and headers
| ID | Requirement | Verification |
|---|---|---|
| PROT-060 | Checks MUST run in the order of the diagram, so that the cheapest refusal is given first and a refused request never reaches storage. | Handler |
| PROT-061 | Authentication errors MUST take precedence over parameter errors, so that an unauthenticated caller learns nothing about valid parameter values. | Handler |
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