Skip to content

Spec Endpoints Service

MAVERICK edited this page Nov 8, 2026 · 2 revisions

Spec: Service Endpoints

Part of the Technical Specification. Requirement prefix: FR-SVC. These operations, except the presenting key (section 5), need no key, are not metered against a quota, and are subject to the per-IP limit only (RATE-001).

1. Source register

GET /v1/sources · operationId listSources

The public attribution and terms register: every source family the API can serve, whether or not the caller's plan includes it.

{
  "data": [
    {
      "family": "roads.federal",
      "domain": "roads",
      "publisher": "Example federal road authority",
      "attributionText": "Data: Example federal road authority, DL-DE BY 2.0",
      "licence": "Datenlizenz Deutschland – Namensnennung – Version 2.0",
      "licenceId": "DL-DE-BY-2.0",
      "licenceUrl": "https://www.govdata.de/dl-de/by-2-0",
      "shareAlike": false,
      "shareAlikeExport": null,
      "conditionNotes": [],
      "purposeNotes": [],
      "termsAcceptanceRequired": false,
      "useClasses": ["consumer", "non_commercial", "commercial"],
      "freshnessTargetS": 900
    }
  ],
  "meta": { "generatedAt": "2026-11-01T13:05:00Z", "registerVersion": "2026-11-01" }
}

GET /v1/sources/{family} returns one entry. Each entry's fragment https://api.viafrei.de/v1/sources#<family> is the target of Link: rel="license" headers.

2. Meta

GET /v1/meta · operationId getMeta

{
  "data": {
    "apiVersion": "1.4.0",
    "platformVersion": "2.6.0",
    "contractVersion": "3.2",
    "openapi": "https://api.viafrei.de/v1/openapi.json",
    "languages": ["de", "en"],
    "deprecations": [],
    "termsOfUse": "https://viafrei.de/…",
    "status": "https://api.viafrei.de/status"
  }
}

Version numbers in the example are placeholders.

3. Health

Path Meaning Answer
/healthz Liveness: the process runs and its event handling is responsive. Never touches storage. 200 {"status":"ok"} or no answer
/readyz Readiness: both storage connections answer within health.ready_timeout, the read contract is compatible, the access store is migrated 200 {"status":"ready"} or 503 {"status":"not_ready","checks":{"storage":"fail"}}

Health answers are unversioned, MUST NOT carry versions, hostnames, addresses or error text, and carry Cache-Control: no-store.

4. Interface description and documentation

Path Content
/v1/openapi.json The OpenAPI 3.1 document for v1, application/vnd.oai.openapi+json;version=3.1 with application/json accepted
/v1/openapi.yaml The same document in YAML
/openapi.json 302 to the newest stable major's document
/docs The rendered reference and guide ([[Spec: Developer Experience
/problems/{type} One documentation page per problem type ([[Spec: Errors

5. The presenting key

GET /v1/key · operationId getKey · needs a key, no scope

The key that made the request: its id, plan, use class, expiry, and the source families the licence gate lets it receive, each with its attribution (Spec: Authentication and Authorisation, Spec: Data Licensing and Attribution). During the last auth.expiry_warning_days before expiry, meta.warnings carries key_expiring. It never returns the secret, the stored MAC or the client address. It answers the refusals of a keyed operation (401 missing-key, invalid-key, key-expired, key-revoked, 429 rate-limited), and 404 feature-disabled on an instance without an access store.

Requirements

ID Requirement Verification
FR-SVC-001 /v1/sources MUST list every family that any plan can receive, with publisher, attribution text, licence name, identifier and URL, share-alike flag, notes and use classes, and MUST be available without a key. Contract
FR-SVC-002 The register MUST be generated from the same register the licence gate reads, so the public list and the gate cannot disagree. Unit
FR-SVC-003 /v1/meta MUST report the API version, the platform version and the read-contract version, and MUST contain no secret, hostname or address (tested). Security
FR-SVC-004 /healthz MUST NOT touch storage; /readyz MUST fail when storage, the contract version or the access-store migrations are not ready. Handler
FR-SVC-005 /v1/openapi.json MUST be byte-identical to the committed, released document of the running version, minus operations disabled by configuration (FR-GEN-006). Contract
FR-SVC-006 Every problem type URI MUST resolve to a human-readable page. Docs

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally