[OpenAPI RFC 8615, catalogo RFC 9727, Sunset RFC 8594]

Discovery e governance

Argus pubblica la propria superficie pubblica tramite discovery allineata agli standard: un descrittore OpenAPI 3.1 sul percorso well-known RFC 8615 (JSON e YAML), un link-set RFC 9727 che punta a ogni artefatto machine-readable, un listing riflessivo e consapevole del tenant degli schemi dati che il chiamante può raggiungere ora, e header Sunset e Deprecation RFC 8594 affinché i partner pianifichino le migrazioni come per qualunque API basata su standard aperti.

Descrittori well-known di OpenAPI

`GET /.well-known/openapi.json` e `GET /.well-known/openapi.yaml` servono il contratto pubblico curato di OpenAPI 3.1 sul percorso well-known RFC 8615. Entrambi non richiedono autenticazione, restituiscono ETag forti derivati da un hash del contenuto e rispettano `If-None-Match` con `304 Not Modified` per consentire un caching aggressivo. Il descrittore è filtrato contro la denylist pubblica di `app/core/public_contract_filter.py`, che rispecchia l’array `denylist` del contratto del sito: rotte interne, admin e di piattaforma non compaiono mai. I due formati sono semanticamente identici; differisce solo la serializzazione.

Link-set del catalogo API

`GET /.well-known/api-catalog` restituisce un link-set RFC 9727 affinché i partner scoprano ogni artefatto machine-readable da un’unica ancora. Ogni voce annuncia `service-desc` (le URI JSON e YAML di OpenAPI), `service-doc` (il sito di documentazione) e `service-meta` (il well-known della chiave di verifica della provenance ML-DSA-65, con `rel="provenance-verify-keys"`). Il Content-Type è `application/linkset+json`. Usalo come endpoint di bootstrap: un singolo fetch fornisce URI sufficienti a guidare il resto dell’integrazione.

Listing riflessivo degli schemi

`GET /v1/discovery/data-schemas` è un listing riflessivo e consapevole del tenant degli schemi JSON che il chiamante può raggiungere ora. Richiede lo scope `argus:discovery:read` su un bearer token. I risultati sono filtrati per `tenant_id` e `organization_id` dal contesto di auth e limitati dalla clearance `secrecy_level` del chiamante. L’opzionale `include_federated=true` estende il listing a sorgenti upstream raggiungibili via canali approvati di Communities of Interest (COI); l’opzionale `secrecy_max=` limita i risultati a un livello di clearance. Ogni voce annuncia una `schema_url` canonica sotto `/.well-known/schemas/{id}.json` per il pinning offline del contratto. Ogni chiamata emette un evento di audit `discovery.schemas.read`.

Header Sunset e Deprecation

Argus emette automaticamente gli header `Sunset` e `Deprecation` RFC 8594 su ogni rotta elencata in `deprecation-matrix.json`. Entrambi i valori sono timestamp IMF-fixdate (`Sun, 06 Nov 2026 08:49:37 GMT`). Un `Link: <successor-version-url>; rel="successor-version"` di accompagnamento punta al successore così che il tooling client mostri il percorso di migrazione senza leggere il changelog. Nessun opt-in: il middleware si applica in modo uniforme, è quindi sufficiente cablare un controllo di header nel client HTTP per esporre gli avvisi di deprecation molto prima della data di sunset.

Come i partner tracciano le versioni del contratto

La versione pubblicata del contratto vive nel campo `info.version` di OpenAPI a `/.well-known/openapi.json` (attualmente `2026.4.0`) e nel contratto del sito a `externalContract.version`. La matrice di deprecation è partizionata per versione di contratto, quindi una sola `GET` al well-known più il controllo di header sulla richiesta live restituisce sia la superficie pubblicata sia le finestre di migrazione per rotta. Le versioni degli SDK seguono il contratto: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` e `argus-client` rilasciano `2026.4.0` per il taglio GA di v2026.4. Le voci CHANGELOG nel bundle curato sono versionate allo stesso modo.

Tooling: Postman, Insomnia, generatori OpenAPI

Poiché il descrittore vive sul percorso well-known RFC 8615, ogni client conforme agli standard lo trova senza configurazione ad-hoc. Postman: importa direttamente da `https://api.knogin.com/.well-known/openapi.json`. Insomnia: stessa URL via `Import From URL`. Stoplight Studio, Redocly CLI e `openapi-generator-cli` risolvono l’URL allo stesso modo. I generatori che preferiscono YAML possono prelevare il payload equivalente da `/.well-known/openapi.yaml`. I partner programmatici di solito partono da `/.well-known/api-catalog`, seguono il link `service-desc` e poi mettono in cache rispetto all’ETag restituito dal well-known di OpenAPI.

Round-trip di discovery

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

Risposta del listing riflessivo degli schemi

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

Pronto a cablare la discovery nel tuo tooling?

Apri la referenza API per il contratto pubblico curato, o parla con Knogin se hai bisogno di aiuto per avviare un’integrazione dagli endpoint well-known.