Skip to content

API Design

mavrovde edited this page Nov 1, 2026 · 2 revisions

API Design

This page is the public contract we intend to implement: the feature-first endpoint plan, the response shape, errors, pagination, GeoJSON, attribution and versioning. It is a plan; the final list is reviewed before implementation and published as an OpenAPI 3.1 document. The normative, numbered requirements are in the Technical Specification, which takes precedence where the two differ.

Conventions

Topic Rule
Base path /v1
Authentication Authorization: Bearer <key> or X-API-Key: <key>; never in the URL
Formats application/json by default; application/geo+json on request; errors as application/problem+json
Field names English, camelCase. Enum values are snake_case strings. Ids are opaque and prefixed (for example pl_…, rs_…, sp_…)
Language The lang parameter, else Accept-Language, selects the language of texts (default de); Content-Language reports it ([[Spec: Protocol
Time ISO 8601 instants in UTC with Z; where people read them, a …Local companion in Europe/Berlin with its offset ([[Spec: Scope, Conventions and References
Unknown fields Clients must ignore fields they do not know; new fields can appear within v1

Locations

Any feature that needs a location accepts one of:

  • at=lat,lon: a coordinate;
  • place=<id>: a place id from the places search;
  • q=<text>: a free-text place. An ambiguous text returns 422 ambiguous-place with the candidates (Spec: Errors, ADR-0003).

"Along" features accept a motorway section (road=…&direction=…&from=…&to=…) or a client route (route=<encoded polyline>; long routes can use POST with the same fields in the body; POST is offered on these long-route operations only, as a safe query, ADR-0005).

Endpoint plan (v1)

Feature Path Answer Scope
Place search GET /v1/places?q=&near=&kind= Place[] places
Place overview (composed) GET /v1/places/{id}/overview?needs= a lamp and the top items per need, with part statuses per part
Describe a point GET /v1/locations/describe?at= place, federal state, district, nearest junction places
Addresses GET /v1/addresses?q= Address[] places
Points of interest GET /v1/points-of-interest?near…&category= PointOfInterest[] places
Motorways GET /v1/motorways road, name, lamp, number of situations roads
Motorway conditions GET /v1/motorways/{road}/conditions?direction=&from=&to= Corridor, lamp, RoadSituation[] roads
Roadworks ahead GET /v1/motorways/{road}/roadworks-ahead?at=&direction=&within_km= situations ordered by distance ahead roads
Conditions in an area GET /v1/road-conditions?near…&kinds= situations and an area lamp roads
Condition history GET /v1/motorways/{road}/conditions/history?from=&to=&cursor= a page of observations roads + history
Route briefing (composed) GET /v1/route-briefing?…&needs= or POST Briefing per part
Refuel GET /v1/refuel-options?near…|along…&product=&sort=price|distance FuelStop[], hydrogen included energy
Charging GET /v1/charging-options?near…|along…&min_kw=&connector=&available_now= ChargingSite[] energy
Parking GET /v1/parking-options?near…|along…&vehicle=car|lorry ParkingSite[] parking
Car sharing GET /v1/sharing-options?near… SharingStation[] parking
Stop search GET /v1/stop-places?q=&near= StopPlace[] transit
Departures GET /v1/stop-places/{id}/departures?modes=&from= Departure[] transit
Disruptions GET /v1/stop-places/{id}/disruptions, GET /v1/disruptions?near… Disruption[] transit
Accessibility GET /v1/stop-places/{id}/accessibility StationAccessibility accessibility
Weather risk GET /v1/weather-risk?near…|along… WeatherRisk weather
Driving rules GET /v1/driving-rules?topic=&vehicle= RuleTopic rules
Sources GET /v1/sources the public attribution and terms register public
Meta and operations GET /v1/meta, /healthz, /readyz, /openapi.json, /docs versions, health, the API description public

Each feature that has a counterpart in the MCP server answers the same facts for the same input; this is tested (see Testing and Quality). Condition history is API-only. Watching a situation over time is not part of v1; it will come later as webhooks or server-sent events, with its own design.

Response shape

{
  "data": {
    "corridor": {"road": "A8", "direction": "west", "fromKm": 0, "toKm": 230},
    "lamp": "amber",
    "situations": [{
      "id": "rs_…",
      "kind": "roadworks",
      "severity": "lane_closed",
      "position": {"fromKm": 112.4, "toKm": 115.0, "junction": "Ulm-West"},
      "validity": {"from": "2026-11-01T05:00:00Z", "fromLocal": "2026-11-01T06:00:00+01:00", "until": "2026-11-14T17:00:00Z", "untilLocal": "2026-11-14T18:00:00+01:00"},
      "headline": "…",
      "geometry": {"type": "LineString", "coordinates": ["…"]}
    }]
  },
  "meta": {
    "asOf": "2026-11-01T13:05:00Z",
    "attribution": [{"family": "roads", "text": "…", "licence": "…", "licenceUrl": "…"}],
    "notes": {"condition": [{"family": "roads", "text": "…verbatim…", "lang": "de"}], "purpose": []},
    "page": {"limit": 50, "hasMore": true, "nextCursor": "eyJ2…"},
    "requestId": "01JC…"
  },
  "links": {"self": "…", "next": "…"}
}

The example is illustrative; values are placeholders. The full envelope is specified in Spec: Common Envelope.

Attribution

  • Every data response carries meta.attribution: one entry per source family that contributed, with the publisher's attribution text, the licence and a licence URL.
  • Condition and purpose notes required by a licence are carried verbatim in meta.notes. They are legal conditions of the data, not captions, and clients displaying the data must show them.
  • A Link: <…/v1/sources#family>; rel="license" header points to the public register.
  • GET /v1/sources lists every source family with its attribution, licence and conditions.

GeoJSON

  • Accept: application/geo+json returns an RFC 7946 FeatureCollection. The meta block is included as a foreign member, so attribution travels with the geometry.
  • geometry=none|point|simplified|full controls geometry detail; coordinates use six decimal places.
  • Geometry is built in the database, so large shapes cost no application CPU.

Pagination

  • Keyset (cursor) pagination only. OFFSET is never used.
  • The cursor is opaque and signed. It binds the position, the time window and a hash of the filters, and it expires. Replaying it with other filters or after expiry returns 400 invalid-cursor.
  • Default page size 50; the maximum depends on the plan and is capped by configuration.
  • History endpoints require a bounded time window (from and to). A missing window is 400 window-required; a window larger than allowed is 400 window-too-large. This keeps every history query on a small, indexed slice of data.

Field selection and compression

  • fields= selects a subset of fields, validated against the response schema.
  • gzip and brotli compression above a minimum size; zstd optional.

Errors (RFC 9457)

Every error is application/problem+json:

{
  "type": "https://api.viafrei.de/problems/overloaded",
  "title": "Service is busy",
  "status": 429,
  "detail": "The bulk tier is at capacity. Retry after 2 seconds.",
  "instance": "/v1/route-briefing",
  "requestId": "01JC…",
  "retryAfter": 2
}

Each type has its own documentation page.

Status Types
400 invalid-parameter (with errors[]), invalid-cursor, window-required, window-too-large, key-in-query
401 missing-key, invalid-key, key-expired, key-revoked
403 scope-denied, source-not-permitted, terms-not-accepted
404 not-found, feature-disabled
405, 406, 412, 413, 414, 415, 431 protocol refusals, see [[Spec: Errors
422 ambiguous-place (with candidates[]), outside-coverage, area-too-large, invalid-section
429 rate-limited, quota-exceeded, overloaded (all with Retry-After)
500 internal (never with internal detail; the request id links to the log)
503 deadline-exhausted, upstream-unavailable, not-ready

409 is not used: the API is read-only. 504 comes only from the TLS edge, never from the service. The complete catalogue is in Spec: Errors.

Rate-limit headers

Every response carries RateLimit-Policy and RateLimit (IETF HTTP API working group draft). Every 429 carries Retry-After. See Rate Limits and Priority.

Versioning and deprecation

  • The major version is in the path (/v1). Within v1, changes are additive only.
  • A breaking change goes to /v2, published beside v1. The old version then carries Deprecation (RFC 9745), Sunset (RFC 8594) and Link rel="deprecation" headers, with at least six months' notice.
  • The OpenAPI document is generated from code and every pull request is checked for breaking changes against main; a breaking change without a major version bump fails CI.
  • The API's version moves in step with the ViaFrei platform's version. GET /v1/meta reports apiVersion, platformVersion and contractVersion.

OpenAPI 3.1

  • Generated from the code (code-first), exported to a committed file, served at /openapi.json and rendered at /docs.
  • Every operation has a summary, a description, its scope, its source families, its MCP counterpart where one exists, and examples that are executed against fixtures in CI.
  • A docs lint fails when an operation lacks any of them.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally