[OpenAPI nach RFC 8615, Katalog nach RFC 9727, Sunset nach RFC 8594]

Discovery und Governance

Argus veröffentlicht seine öffentliche API-Oberfläche über standardskonforme Discovery: einen OpenAPI-3.1-Descriptor unter dem RFC-8615-Well-known-Pfad (JSON und YAML), ein RFC-9727-Linkset, das auf jedes maschinenlesbare Artefakt verweist, ein tenant-bewusstes reflektives Listing der Datenschemata, die der Aufrufer aktuell erreichen kann, und RFC-8594-Sunset- und Deprecation-Header, damit Partner Migrationen genauso planen wie bei jeder Open-Standards-API.

Well-known-OpenAPI-Descriptoren

`GET /.well-known/openapi.json` und `GET /.well-known/openapi.yaml` liefern den kuratierten öffentlichen OpenAPI-3.1-Vertrag am RFC-8615-Well-known-Pfad. Beide Endpoints benötigen keine Authentifizierung, geben starke ETags auf Basis eines Content-Hashes zurück und respektieren `If-None-Match` mit `304 Not Modified`, damit Tooling aggressiv cachen kann. Der Descriptor wird gegen die öffentliche Denylist aus `app/core/public_contract_filter.py` gefiltert, die das `denylist`-Array im Website-Vertrag spiegelt: interne, Admin- und Plattform-Routen erscheinen nie. Beide Formate sind semantisch identisch; nur die Serialisierung unterscheidet sich.

API-Katalog-Linkset

`GET /.well-known/api-catalog` liefert ein RFC-9727-Linkset, sodass Partner jedes maschinenlesbare Artefakt von einem Ankerpunkt aus entdecken können. Jeder Eintrag annonciert `service-desc` (die JSON- und YAML-Well-known-URIs der OpenAPI), `service-doc` (die veröffentlichte Dokumentations-Site) und `service-meta` (das Well-known der ML-DSA-65-Provenance-Verify-Keys mit `rel="provenance-verify-keys"`). Content-Type ist `application/linkset+json`. Nutzen Sie es als Bootstrap-Endpoint: ein einziger Fetch liefert genug URIs, um den Rest der Integration zu fahren.

Reflektives Schema-Listing

`GET /v1/discovery/data-schemas` ist ein tenant-bewusstes, reflektives Listing der JSON-Schemata, die der Aufrufer jetzt erreichen kann. Es erfordert den Scope `argus:discovery:read` auf einem Bearer-Token. Ergebnisse werden nach `tenant_id` und `organization_id` aus dem Auth-Kontext gefiltert und gegen die `secrecy_level`-Clearance des Aufrufers begrenzt. Optionales `include_federated=true` erweitert das Listing um Upstream-Quellen, die über genehmigte Communities-of-Interest-Kanäle erreichbar sind; optionales `secrecy_max=` begrenzt die Ergebnisse auf eine Clearance-Stufe. Jeder Schema-Eintrag annonciert eine kanonische `schema_url` unter `/.well-known/schemas/{id}.json` für Offline-Vertragsbindung. Jeder Aufruf schreibt ein Audit-Event `discovery.schemas.read`.

Sunset- und Deprecation-Header

Argus emittiert RFC-8594-`Sunset`- und `Deprecation`-Header automatisch auf jeder Route, die in `deprecation-matrix.json` gelistet ist. Beide Werte sind IMF-fixdate-Zeitstempel (`Sun, 06 Nov 2026 08:49:37 GMT`). Ein begleitender `Link: <successor-version-url>; rel="successor-version"` zeigt auf den Nachfolger, sodass Client-Tooling den Migrationspfad ohne Changelog-Lektüre anzeigen kann. Es gibt kein Opt-in: Die Middleware wirkt einheitlich, sodass Partner eine einzige Header-Prüfung in ihrem HTTP-Client verdrahten und Deprecation-Hinweise lange vor dem Sunset-Termin sichtbar machen können.

Wie Partner Vertragsversionen tracken

Die veröffentlichte Vertragsversion steht im OpenAPI-`info.version`-Feld unter `/.well-known/openapi.json` (aktuell `2026.4.0`) und im Website-Vertrag unter `externalContract.version`. Die Deprecation-Matrix ist nach Vertragsversion partitioniert, sodass ein einziges `GET` gegen das Well-known plus eine Header-Prüfung am Live-Request sowohl die veröffentlichte Oberfläche als auch alle Routen-spezifischen Migrationsfenster liefert. SDK-Versionen folgen dem Vertrag: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` und `argus-client` liefern `2026.4.0` zum v2026.4-GA-Cut. CHANGELOG-Einträge im kuratierten Bundle werden gleich versioniert.

Tooling: Postman, Insomnia, OpenAPI-Generatoren

Da der Descriptor am RFC-8615-Well-known-Pfad liegt, findet ihn jeder standardskonforme Client ohne spezielle Konfiguration. Postman: direkter Import aus `https://api.knogin.com/.well-known/openapi.json`. Insomnia: dieselbe URL via `Import From URL`. Stoplight Studio, Redocly CLI und `openapi-generator-cli` lösen die URL identisch auf. Generatoren, die YAML bevorzugen, ziehen den äquivalenten Payload aus `/.well-known/openapi.yaml`. Programmatische Partner starten typischerweise mit `/.well-known/api-catalog`, folgen dem `service-desc`-Link und cachen anschließend gegen das ETag, das das OpenAPI-Well-known zurückgibt.

Discovery-Roundtrip

# 1. Bootstrap from the API catalog link-set
curl https://api.knogin.com/.well-known/api-catalog

# 2. Fetch the OpenAPI 3.1 descriptor (JSON or YAML)
curl https://api.knogin.com/.well-known/openapi.json
curl https://api.knogin.com/.well-known/openapi.yaml

# 3. List the data schemas the caller's tenant + clearance can see
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.knogin.com/v1/discovery/data-schemas?include_federated=true"

# 4. Watch for Sunset / Deprecation headers on any live route
curl -i -H "Authorization: Bearer $TOKEN" https://api.knogin.com/v1/profiles/abc | head
# Sunset: Sun, 06 Nov 2026 08:49:37 GMT
# Deprecation: Sun, 06 Nov 2026 08:49:37 GMT
# Link: <https://api.knogin.com/v2/profiles/abc>; rel="successor-version"

Antwort des reflektiven Schema-Listings

{
  "tenant_id": "tnt_123",
  "schemas": [
    {
      "id": "argus.profile.v1",
      "title": "Profile",
      "secrecy_level": "standard",
      "operations": [
        "GET /v1/profiles/{id}",
        "POST /v1/profiles/{id}/enrich"
      ],
      "schema_url": "https://api.knogin.com/.well-known/schemas/argus.profile.v1.json"
    }
  ],
  "federated_sources": []
}

Bereit, Discovery in Ihr Tooling zu verdrahten?

Öffnen Sie die API-Referenz für den kuratierten öffentlichen Vertrag oder sprechen Sie mit Knogin, wenn Sie Hilfe beim Bootstrap einer Integration aus den Well-known-Endpoints brauchen.