Knogin
[OpenAPI RFC 8615, catalogus RFC 9727, Sunset RFC 8594]

Discovery en governance

Argus publiceert zijn publieke API-oppervlak via standaard-conforme discovery: een OpenAPI 3.1-descriptor op het RFC 8615 well-known-pad (JSON en YAML), een RFC 9727 link-set die naar elk machineleesbaar artefact wijst, een tenant-bewuste reflectieve listing van de dataschema’s die de caller nu kan bereiken, en RFC 8594 Sunset- en Deprecation-headers zodat partners migraties net zo plannen als bij elke open-standaarden-API.

Discovery en governance

Well-known OpenAPI-descriptors

`GET /.well-known/openapi.json` en `GET /.well-known/openapi.yaml` serveren het gecureerde publieke OpenAPI 3.1-contract op het RFC 8615 well-known-pad. Beide zijn niet-geauthenticeerd, retourneren sterke ETags afgeleid van een content-hash en honoreren `If-None-Match` met `304 Not Modified` zodat tooling agressief kan cachen. De descriptor wordt gefilterd tegen de publieke denylist uit `app/core/public_contract_filter.py`, die de `denylist`-array van het sitecontract spiegelt: interne, admin- en platformroutes verschijnen nooit. Beide formaten zijn semantisch identiek; alleen de serialisatie verschilt.

API-catalogus link-set

`GET /.well-known/api-catalog` retourneert een RFC 9727 link-set zodat partners elk machineleesbaar artefact vanuit één anker ontdekken. Elke entry kondigt `service-desc` aan (de JSON- en YAML-well-known-URIs van OpenAPI), `service-doc` (de gepubliceerde documentatiesite) en `service-meta` (de ML-DSA-65 provenance-verify-key well-known met `rel="provenance-verify-keys"`). Content-Type is `application/linkset+json`. Gebruik dit als bootstrap-endpoint: één fetch levert genoeg URIs voor de rest van de integratie.

Reflectieve dataschema-listing

`GET /v1/discovery/data-schemas` is een tenant-bewuste reflectieve listing van de JSON-schema’s die de caller nu kan bereiken. Vereist de scope `argus:discovery:read` op een bearer token. Resultaten worden gefilterd op `tenant_id` en `organization_id` uit de auth-context en geclamped tegen de `secrecy_level`-clearance van de caller. Optionele `include_federated=true` breidt de listing uit met upstream-bronnen bereikbaar via goedgekeurde Communities of Interest (COI)-kanalen; optionele `secrecy_max=` clampt resultaten op een clearance-niveau. Elke schema-entry kondigt een canonieke `schema_url` aan onder `/.well-known/schemas/{id}.json` voor offline contractpinning. Elke call schrijft een audit-event `discovery.schemas.read`.

Sunset- en Deprecation-headers

Argus emit RFC 8594 `Sunset`- en `Deprecation`-headers automatisch op elke route in `deprecation-matrix.json`. Beide waarden zijn IMF-fixdate timestamps (`Sun, 06 Nov 2026 08:49:37 GMT`). Een begeleidende `Link: <successor-version-url>; rel="successor-version"` wijst naar de opvolger, zodat client-tooling het migratiepad kan tonen zonder de changelog te lezen. Er is geen opt-in: de middleware werkt uniform, dus partners kunnen één header-check in hun HTTP-client verdraden en deprecation-meldingen ruim voor de sunset-datum aan operators tonen.

Hoe partners contractversies volgen

De gepubliceerde contractversie staat in het OpenAPI-veld `info.version` op `/.well-known/openapi.json` (op dit moment `2026.4.0`) en op het sitecontract bij `externalContract.version`. De deprecation-matrix is gepartitioneerd per contractversie, dus één `GET` op het well-known plus een header-check op de live-request geeft zowel het gepubliceerde oppervlak als per-route-migratievensters. SDK-versies volgen het contract: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` en `argus-client` leveren allemaal `2026.4.0` voor de v2026.4 GA-cut. CHANGELOG-entries in de gecureerde bundle worden hetzelfde geversioneerd.

Tooling: Postman, Insomnia, OpenAPI-generators

Omdat de descriptor op het RFC 8615 well-known-pad leeft, vindt elke standaard-bewuste client hem zonder maatwerkconfiguratie. Postman: importeer rechtstreeks vanaf `https://api.knogin.com/.well-known/openapi.json`. Insomnia: dezelfde URL via `Import From URL`. Stoplight Studio, Redocly CLI en `openapi-generator-cli` lossen de URL op dezelfde manier op. Generators die YAML prefereren halen de equivalente payload uit `/.well-known/openapi.yaml`. Programmatische partners starten meestal met `/.well-known/api-catalog`, volgen de `service-desc`-link en cachen vervolgens tegen de ETag die de OpenAPI-well-known retourneert.

Discovery-round-trip

# 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"

Reactie van de reflectieve dataschema-listing

{
  "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": []
}

Klaar om discovery in je tooling te verdraden?

Open de API-referentie voor het gecureerde publieke contract, of praat met Knogin als je hulp nodig hebt om een integratie vanuit de well-known-endpoints op te starten.