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

Découverte et gouvernance

Argus publie sa surface publique via une découverte alignée sur les standards : un descripteur OpenAPI 3.1 well-known RFC 8615 (JSON et YAML), un link-set RFC 9727 qui pointe vers chaque artefact lisible par machine, un listage réflexif des schémas de données accessibles par l’appelant en fonction de son tenant, et des en-têtes Sunset et Deprecation RFC 8594 pour que les partenaires planifient les migrations comme avec n’importe quelle API basée sur des standards ouverts.

Descripteurs well-known OpenAPI

`GET /.well-known/openapi.json` et `GET /.well-known/openapi.yaml` servent le contrat public curé OpenAPI 3.1 sur le chemin well-known RFC 8615. Les deux endpoints sont non authentifiés, renvoient des ETags forts dérivés d’un hash de contenu et honorent `If-None-Match` avec `304 Not Modified` pour permettre un cache agressif. Le descripteur est filtré contre la denylist publique de `app/core/public_contract_filter.py`, miroir du tableau `denylist` du contrat du site : les routes internes, admin et plateforme n’apparaissent jamais. Les deux formats sont sémantiquement équivalents ; seule la sérialisation diffère.

Link-set du catalogue d’API

`GET /.well-known/api-catalog` renvoie un link-set RFC 9727 pour que les partenaires découvrent chaque artefact lisible par machine depuis une seule ancre. Chaque entrée annonce `service-desc` (les URIs JSON et YAML d’OpenAPI), `service-doc` (le site de documentation) et `service-meta` (le well-known de la clé de vérification de provenance ML-DSA-65, avec `rel="provenance-verify-keys"`). Le Content-Type est `application/linkset+json`. Utilisez-le comme point d’amorçage : un seul appel renvoie assez d’URIs pour piloter le reste de l’intégration.

Listage réflexif des schémas

`GET /v1/discovery/data-schemas` est un listage réflexif et conscient du tenant des schémas JSON accessibles maintenant. Il exige le scope `argus:discovery:read` sur un bearer token. Les résultats sont filtrés par `tenant_id` et `organization_id` issus du contexte d’authentification et plafonnés selon la clearance `secrecy_level` de l’appelant. L’option `include_federated=true` étend le listage aux sources amont accessibles via des canaux Communities of Interest (COI) approuvés ; `secrecy_max=` plafonne les résultats à un niveau de clearance. Chaque entrée annonce une `schema_url` canonique sous `/.well-known/schemas/{id}.json` pour le pinning offline. Chaque appel émet un événement d’audit `discovery.schemas.read`.

En-têtes Sunset et Deprecation

Argus émet automatiquement les en-têtes `Sunset` et `Deprecation` RFC 8594 sur chaque route listée dans `deprecation-matrix.json`. Les deux valeurs sont des timestamps IMF-fixdate (`Sun, 06 Nov 2026 08:49:37 GMT`). Un `Link: <successor-version-url>; rel="successor-version"` complémentaire pointe vers le remplacement pour que les outils clients fassent remonter le chemin de migration sans lire le changelog. Pas d’opt-in : le middleware s’applique uniformément, il suffit donc de câbler une vérification d’en-têtes dans le client HTTP pour alerter les opérateurs bien avant la date de sunset.

Comment les partenaires suivent les versions du contrat

La version publiée du contrat se trouve dans le champ `info.version` d’OpenAPI à `/.well-known/openapi.json` (actuellement `2026.4.0`) et sur le contrat du site à `externalContract.version`. La matrice de déprécation est partitionnée par version de contrat : un seul `GET` sur le well-known plus la vérification d’en-tête sur la requête live donne à la fois la surface publiée et les fenêtres de migration par route. Les versions des SDK suivent le contrat : `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` et `argus-client` livrent `2026.4.0` pour la GA v2026.4. Les entrées du CHANGELOG du bundle curé sont versionnées de la même manière.

Outils : Postman, Insomnia, générateurs OpenAPI

Comme le descripteur réside au chemin well-known RFC 8615, tout client conforme aux standards le trouve sans configuration spécifique. Postman : importez directement depuis `https://api.knogin.com/.well-known/openapi.json`. Insomnia : même URL via `Import From URL`. Stoplight Studio, Redocly CLI et `openapi-generator-cli` résolvent l’URL de la même façon. Les générateurs qui préfèrent YAML peuvent tirer le payload équivalent depuis `/.well-known/openapi.yaml`. Les partenaires programmatiques démarrent typiquement par `/.well-known/api-catalog`, suivent le lien `service-desc` puis cachent contre l’ETag renvoyé par le well-known OpenAPI.

Aller-retour de découverte

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

Réponse du listage réflexif des schémas

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

Prêt à câbler la découverte dans vos outils ?

Ouvrez la référence d’API pour le contrat public curé, ou contactez Knogin si vous avez besoin d’aide pour amorcer une intégration depuis les endpoints well-known.