Skip to content

Spec Protocol

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Protocol

Part of the Technical Specification. Requirement prefix: PROT. Conventions: Spec: Scope, Conventions and References.

1. Transport and address

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

2. Methods

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]].

3. Content negotiation, encoding, charset

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.

4. Headers

4.1 Request headers

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)

4.2 Response headers

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

5. Conditional requests and caching

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]
Loading
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

6. CORS

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

7. Request lifecycle (normative order)

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
Loading
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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally