[OpenAPI RFC 8615, catálogo RFC 9727, Sunset RFC 8594]

Descubrimiento y gobernanza

Argus publica su superficie pública mediante un descubrimiento alineado con estándares: un descriptor OpenAPI 3.1 en la ruta well-known de RFC 8615 (JSON y YAML), un link-set RFC 9727 que apunta a todos los artefactos legibles por máquina, un listado reflexivo y consciente del tenant de los esquemas de datos que el solicitante puede alcanzar ahora mismo, y cabeceras Sunset y Deprecation de RFC 8594 para que los partners planifiquen migraciones igual que con cualquier API basada en estándares abiertos.

Descriptores well-known de OpenAPI

`GET /.well-known/openapi.json` y `GET /.well-known/openapi.yaml` sirven el contrato público curado de OpenAPI 3.1 en la ruta well-known de RFC 8615. Ambos no requieren autenticación, devuelven ETags fuertes derivados de un hash de contenido y respetan `If-None-Match` con `304 Not Modified` para que las herramientas puedan cachear con confianza. El descriptor se filtra contra la denylist pública de `app/core/public_contract_filter.py`, que refleja la lista `denylist` del contrato del sitio: las rutas internas, administrativas y de plataforma nunca aparecen. Ambos formatos son equivalentes a nivel semántico; solo difiere la serialización.

Link-set del catálogo de API

`GET /.well-known/api-catalog` devuelve un link-set RFC 9727 para que los partners descubran cada artefacto legible por máquina desde un único ancla. Cada entrada anuncia `service-desc` (las URIs JSON y YAML de OpenAPI), `service-doc` (el sitio de documentación) y `service-meta` (la well-known de la clave de verificación de provenance ML-DSA-65, con `rel="provenance-verify-keys"`). El Content-Type es `application/linkset+json`. Úsalo como punto de arranque: una sola petición devuelve suficientes URIs para impulsar el resto de la integración.

Listado reflexivo de esquemas

`GET /v1/discovery/data-schemas` es un listado reflexivo y consciente del tenant de los esquemas JSON que el solicitante puede alcanzar ahora mismo. Requiere el scope `argus:discovery:read` sobre un bearer token. Los resultados se filtran por `tenant_id` y `organization_id` del contexto de autenticación y se acotan contra la clearance `secrecy_level` del solicitante. El opcional `include_federated=true` extiende el listado a fuentes upstream alcanzables vía canales aprobados de Communities of Interest (COI); el opcional `secrecy_max=` acota los resultados a un nivel. Cada entrada anuncia una `schema_url` canónica bajo `/.well-known/schemas/{id}.json` para fijar el contrato offline. Cada llamada emite un evento de auditoría `discovery.schemas.read`.

Cabeceras Sunset y Deprecation

Argus emite cabeceras `Sunset` y `Deprecation` de RFC 8594 automáticamente en cada ruta listada en `deprecation-matrix.json`. Ambos valores son timestamps IMF-fixdate (`Sun, 06 Nov 2026 08:49:37 GMT`). Un `Link: <successor-version-url>; rel="successor-version"` complementario apunta al reemplazo para que las herramientas cliente muestren el camino de migración sin leer el changelog. No hay opt-in: el middleware se aplica uniformemente a toda la superficie, así que basta cablear una verificación de cabecera en el cliente HTTP para alertar a los operadores con mucha antelación.

Cómo siguen los partners las versiones del contrato

La versión publicada del contrato vive en el campo `info.version` del OpenAPI en `/.well-known/openapi.json` (actualmente `2026.4.0`) y en el contrato del sitio web en `externalContract.version`. La matriz de deprecación se particiona por versión de contrato, así que un único `GET` al well-known más la verificación de cabecera en la solicitud en vivo proporciona tanto la superficie publicada como las ventanas de migración por ruta. Las versiones de SDK siguen el contrato: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` y `argus-client` envían `2026.4.0` para el corte GA de v2026.4. Las entradas del CHANGELOG en el bundle curado se versionan igual.

Herramientas: Postman, Insomnia, generadores OpenAPI

Como el descriptor reside en la ruta well-known de RFC 8615, cualquier cliente alineado con estándares lo encuentra sin configuración a medida. Postman: importa directamente desde `https://api.knogin.com/.well-known/openapi.json`. Insomnia: la misma URL en `Import From URL`. Stoplight Studio, Redocly CLI y `openapi-generator-cli` resuelven la URL del mismo modo. Los generadores que prefieren YAML pueden tirar el payload equivalente de `/.well-known/openapi.yaml`. Los partners programáticos suelen empezar por `/.well-known/api-catalog`, seguir el enlace `service-desc` y cachear contra el ETag que devuelve el well-known de OpenAPI.

Recorrido de descubrimiento

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

Respuesta del listado reflexivo de esquemas

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

¿Listo para cablear el descubrimiento en tus herramientas?

Abre la referencia de API para el contrato público curado, o habla con Knogin si necesitas ayuda para arrancar una integración desde los endpoints well-known.