infranode-dev Meta API

openapi: 3.2.0
info:
  title: InfraNode Meta API
  version: 1.0.0
  description: 'Open-Source-Proxy-REST-API für normalisierte offene Daten deutscher Großstädte. Bekannt sind 84 Städte über 100.000 Einwohner, davon 28 Kern-Städte mit voller Quellen-Abdeckung; weitere Städte werden über AGS- und geobasierte Quellen bedient. Jede Antwort folgt demselben kanonischen Envelope (data/meta/attribution) mit Lizenz-Tag und ehrlichem source_status (ok/no_data/disabled/not_covered). Teilabgedeckte Endpunkte (flood, traffic, road-events) liefern für eine nicht-abgedeckte Stadt 200 source_status="not_covered" + meta.covered_cities statt eines leeren "ok"; die Abdeckung listet die Seite /abdeckung. Pfade tragen den vollen /api/v1-Prefix, damit die ausgelieferte Spec driftfrei zu den live registrierten Routen bleibt. Paginierung ist kanal-abhängig: direktes REST liefert Datenart-Listen voll, GPT-Actions und MCP sind serverseitig bzw. client-seitig auf ein Default-Limit gebunden; limit=all (bzw. ?all=1) erzwingt kanalunabhängig die Vollausgabe. Details siehe meta.pagination (Meta-Schema). Der Stadt-Slug im Pfad wird tolerant aufgelöst: der deutsche Name mit oder ohne Umlaute, beliebige Groß/Kleinschreibung, gängige englische Exonyme und Kurzformen führen zum kanonischen Slug (München/münchen/munich/munchen -> muenchen, cologne -> koeln, frankfurt -> frankfurt-am-main). Ein unbekannter Name liefert 404 mit einem "Meintest du ...?"-Hinweis auf den nächstliegenden Slug; die kanonischen Slugs listet GET /api/v1/cities. Feldnamen-Konvention (seit 2026-07-25 vereinheitlicht): Felder heissen durchgaengig snake_case und englisch. Gleiche Konzepte tragen ueberall denselben Namen: post_code (immer fuenfstelliger String, fuehrende Null bleibt erhalten), street, house_number, place, name, start, end, distance_km, power_kw, lat/lon. Fehlt eine Angabe in der Quelle, ist das Feld null statt Leerstring. Zeitstempel tragen immer eine Zeitzone. Uebergangsweise stehen die frueheren Namen (plz, zip, strasse, hausnummer, ort, city, bezeichnung, beginn, ende, art, dist_km, leistung_kw, einheit_typ sowie die camelCase-Rohfelder des Autobahn-Feeds) mit identischem Wert daneben; sie sind ABGEKUENDIGT und werden fruehestens 30 Tage nach der Ankuendigung im Changelog entfernt.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://infranode.dev
  description: Öffentliche gehostete API, keylos (Standard)
- url: http://localhost
  description: Lokaler Caddy-Ingress (Docker Compose)
tags:
- name: Meta
  description: Meta- und Diagnose-Routen (Health, Ping, Source-Status, Spec)
paths:
  /api/v1/health:
    get:
      tags:
      - Meta
      summary: Liveness und Readiness der App prüfen
      x-summary-en: Check app liveness and readiness
      description: 'Liefert den App-Status und die Redis-Erreichbarkeit. Gedacht für Uptime-Monitore und Load-Balancer-Probes: antwortet mit 200, sobald die App bereit ist, sonst mit einem Fehlerstatus.'
      x-description-en: 'Returns the app status and Redis reachability. Designed for uptime monitors and load-balancer probes: responds with 200 once the app is ready, otherwise with an error status.'
      operationId: getHealth
      responses:
        '200':
          description: App läuft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
  /api/v1/sources:
    get:
      tags:
      - Meta
      summary: Status aller Upstream-Quellen
      x-summary-en: Status of all upstream sources
      description: Listet je bekannter Quelle den enabled-Zustand (aus den Settings) und den Circuit-Breaker-Zustand (CLOSED/OPEN/HALF_OPEN). So ist auf einen Blick sichtbar, welche Quelle gerade liefert und welche pausiert ist.
      x-description-en: Lists each known source with its enabled state (from settings) and its circuit-breaker state (CLOSED/OPEN/HALF_OPEN). Shows at a glance which source is currently serving and which is paused.
      operationId: getSources
      responses:
        '200':
          description: Liste der Quellen-Status
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SourceStatus'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '304':
          $ref: '#/components/responses/NotModified'
      parameters:
      - in: header
        name: If-None-Match
        required: false
        schema:
          type: string
        description: Conditional GET. Stimmt der Wert mit dem aktuellen ETag überein, antwortet der Server mit 304 Not Modified ohne Body.
        x-description-en: Conditional GET. If the value matches the current ETag, the server responds with 304 Not Modified and no body.
      - in: query
        name: page
        schema:
          type: integer
          minimum: 1
          default: 1
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          default: 50
        description: 'Seitengröße. Wird auf MAX_LIMIT (200) gedeckelt: zu große Werte liefern eine 200er-Seite mit 200 Einträgen statt eines Fehlers.'
        x-description-en: 'Page size. Capped at MAX_LIMIT (200): larger values return a 200 page of 200 items instead of an error.'
      - in: query
        name: offset
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Ein zu großer Offset liefert eine leere Seite (200), nie 500.
        x-description-en: An offset past the end returns an empty page (200), never 500.
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - source
          - enabled
          - license
        description: Nur die gelisteten Felder sind erlaubt; ein unbekanntes Feld wird mit 400 (invalid_request) abgewiesen, bevor es ausgewertet wird.
        x-description-en: Only the listed fields are allowed; an unknown field is rejected with 400 (invalid_request) before it is evaluated.
      - in: query
        name: order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
  /api/v1/openapi.yaml:
    get:
      tags:
      - Meta
      summary: Diese OpenAPI-Spec als YAML
      x-summary-en: This OpenAPI spec as YAML
      description: Liefert die handgepflegte Spec als application/yaml. FastAPI serviert intern nur /openapi.json; diese Route stellt die stabile YAML-Variante bereit.
      x-description-en: Returns the hand-maintained spec as application/yaml. FastAPI internally serves only /openapi.json; this route provides the stable YAML variant.
      operationId: getOpenapiYaml
      responses:
        '200':
          description: Die Spec als YAML
          content:
            application/yaml:
              schema:
                type: string
components:
  responses:
    NotModified:
      description: Not Modified. If-None-Match stimmte mit dem aktuellen ETag überein; es wird kein Body geliefert (ETag + Cache-Control bleiben erhalten).
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
  schemas:
    Meta:
      type: object
      properties:
        correlation_id:
          type: string
          nullable: true
        source_status:
          type: string
          description: Ehrlicher Quellen-Status der Antwort. "ok" (Daten vorhanden), "no_data" (Quelle erreichbar/abgedeckt, aber gerade keine Daten), "disabled" (Quelle per Toggle aus), "not_ingested" (kein Snapshot), "not_covered" (Stadt ist für diesen teilabgedeckten Endpunkt strukturell nicht abgedeckt; data=null, siehe covered_cities). Klar unterscheidbar vom 404 (Stadt unbekannt).
          enum:
          - ok
          - no_data
          - disabled
          - not_ingested
          - not_covered
        cache_status:
          type: string
          nullable: true
          description: Cache-Herkunft (hit/miss/stale), sofern die Route cacht.
        covered_cities:
          type: array
          items:
            type: string
          description: 'Nur bei source_status="not_covered": die Stadt-Slugs, die dieser teilabgedeckte Endpunkt tatsächlich bedient (z. B. flood, traffic, road-events).'
        pagination:
          type: object
          description: 'Bei paginierbaren Datenart-Listen (charging, energy, events, transit, OSM-Feature-Endpunkte): der EHRLICH ausgewiesene Ausschnitt (keine stille Kappung). KANAL-ABHÄNGIGER Default für gleiche URL: direktes REST liefert die volle Liste (limit=null, returned==total, truncated=false); GPT-Actions (erkannt am OpenAI-Header) bekommen ein serverseitig gebundenes Default-Limit; MCP-Aufrufe sind gebunden, weil der MCP-Client selbst ein Default-Limit setzt. Kanalunabhängige Overrides: limit=all (oder ?all=1) erzwingt die volle Liste, limit + offset blättern gezielt. meta.pagination ist bei ALLEN Kanälen gesetzt.'
          x-description-en: 'For paginable data-type lists (charging, energy, events, transit, OSM feature endpoints): the honestly reported slice (no silent capping). CHANNEL-DEPENDENT default for the same URL: direct REST returns the full list (limit=null, returned==total, truncated=false); GPT Actions (detected via the OpenAI header) get a server-side bound default limit; MCP calls are bound because the MCP client sets a default limit itself. Channel-independent overrides: limit=all (or ?all=1) forces the full list, limit + offset page explicitly. meta.pagination is set on ALL channels.'
          properties:
            total:
              type: integer
              description: Gesamtzahl der Einträge (voller Bestand).
            returned:
              type: integer
              description: Zahl der auf dieser Seite ausgelieferten Einträge.
            limit:
              type: integer
              nullable: true
              description: Angewandtes Seiten-Limit; null bei Vollausgabe (REST-Default oder limit=all).
            offset:
              type: integer
              description: Start-Offset der Seite.
            truncated:
              type: boolean
              description: true, wenn hinter dieser Seite noch Einträge liegen (offset + returned < total); bei Vollausgabe false.
    Health:
      type: object
      required:
      - status
      - version
      - redis
      properties:
        status:
          type: string
          example: ok
        version:
          type: string
          example: 1.0.0
        redis:
          type: boolean
          description: true wenn Redis erreichbar (Ping erfolgreich)
    SourceStatus:
      type: object
      required:
      - source
      - enabled
      - breaker_state
      properties:
        source:
          type: string
          example: wikidata
        enabled:
          type: boolean
        breaker_state:
          type: string
          enum:
          - CLOSED
          - OPEN
          - HALF_OPEN
  headers:
    ETag:
      description: Stabiler Entity-Tag des Response-Bodys (sha256-basiert). Nur auf erfolgreichen GET-Reads (200) gesetzt, nie auf Fehler-Envelopes/503.
      schema:
        type: string
    CacheControl:
      description: Cache-Control je Ressource ("public, max-age=<ttl>, stale-while-revalidate=<ttl>, stale-if-error=<ttl>"). TTL aus der serverseitigen CACHE_TTL-Map (z.B. wikidata 86400 s, dwd 1800 s, uba 600 s, default 300 s). stale-while-revalidate/stale-if-error erlauben einem Shared Cache (Cloudflare), bei Ablauf bzw. Origin-Fehler kurz die letzte gute Antwort weiterzuliefern. Echtzeit-Endpunkte (/api/v1/live/*) liefern stattdessen "no-store".
      schema:
        type: string