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.

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 Accept-Language selects the language of texts; Content-Language reports it
Time ISO 8601 with offset, rendered in Europe/Berlin
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 409 ambiguous-place with the candidates.

"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).

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-01T06:00:00+01:00", "until": "2026-11-14T18:00:00+01:00"},
      "headline": "…",
      "geometry": {"type": "LineString", "coordinates": ["…"]}
    }]
  },
  "meta": {
    "asOf": "2026-11-01T14:05:00+01:00",
    "attribution": [{"family": "roads", "text": "…", "licence": "…", "licenceUrl": "…"}],
    "notes": {"condition": ["…verbatim…"], "purpose": []},
    "page": {"next": "eyJ2…", "limit": 50},
    "requestId": "01JC…"
  }
}

The example is illustrative; values are placeholders.

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|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, area-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
409 ambiguous-place
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

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