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

Descoberta e governança

A Argus publica a sua superfície pública via descoberta alinhada com padrões: um descritor OpenAPI 3.1 no caminho well-known RFC 8615 (JSON e YAML), um link-set RFC 9727 que aponta para cada artefacto legível por máquina, uma listagem reflexiva e consciente do tenant dos esquemas de dados que o solicitante consegue alcançar agora, e cabeçalhos Sunset e Deprecation RFC 8594 para que os parceiros planeiem migrações tal como em qualquer API baseada em padrões abertos.

Descritores well-known de OpenAPI

`GET /.well-known/openapi.json` e `GET /.well-known/openapi.yaml` servem o contrato público curado de OpenAPI 3.1 no caminho well-known RFC 8615. Ambos são não autenticados, devolvem ETags fortes derivados de um hash de conteúdo e respeitam `If-None-Match` com `304 Not Modified` para que o tooling possa cachear de forma agressiva. O descritor é filtrado contra a denylist pública de `app/core/public_contract_filter.py`, que espelha o array `denylist` do contrato do site: rotas internas, administrativas e de plataforma nunca aparecem. Ambos os formatos são semanticamente idênticos; só a serialização difere.

Link-set do catálogo de API

`GET /.well-known/api-catalog` devolve um link-set RFC 9727 para que os parceiros descubram cada artefacto legível por máquina a partir de uma única âncora. Cada entrada anuncia `service-desc` (as URIs JSON e YAML do OpenAPI), `service-doc` (o site de documentação) e `service-meta` (o well-known da chave de verificação de provenance ML-DSA-65, com `rel="provenance-verify-keys"`). O Content-Type é `application/linkset+json`. Usa-o como ponto de arranque: um único fetch entrega URIs suficientes para alimentar o resto da integração.

Listagem reflexiva de esquemas

`GET /v1/discovery/data-schemas` é uma listagem reflexiva e consciente do tenant dos esquemas JSON que o solicitante pode alcançar agora. Requer o scope `argus:discovery:read` num bearer token. Os resultados são filtrados por `tenant_id` e `organization_id` do contexto de autenticação e limitados pela clearance `secrecy_level` do solicitante. O opcional `include_federated=true` estende a listagem a fontes upstream alcançáveis via canais aprovados de Communities of Interest (COI); o opcional `secrecy_max=` limita os resultados a um nível de clearance. Cada entrada anuncia uma `schema_url` canónica em `/.well-known/schemas/{id}.json` para fixação offline do contrato. Cada chamada emite um evento de auditoria `discovery.schemas.read`.

Cabeçalhos Sunset e Deprecation

A Argus emite cabeçalhos `Sunset` e `Deprecation` RFC 8594 automaticamente em cada rota listada em `deprecation-matrix.json`. Ambos os valores são timestamps IMF-fixdate (`Sun, 06 Nov 2026 08:49:37 GMT`). Um `Link: <successor-version-url>; rel="successor-version"` complementar aponta para o sucessor para que o tooling cliente mostre o caminho de migração sem ler o changelog. Não há opt-in: o middleware aplica-se uniformemente, basta cablar uma verificação de cabeçalho no cliente HTTP para mostrar avisos de deprecation muito antes da data de sunset.

Como os parceiros seguem versões do contrato

A versão publicada do contrato vive no campo `info.version` do OpenAPI em `/.well-known/openapi.json` (atualmente `2026.4.0`) e no contrato do site em `externalContract.version`. A matriz de deprecation é particionada por versão de contrato, por isso um único `GET` ao well-known mais a verificação de cabeçalho no pedido em produção dá tanto a superfície publicada como as janelas de migração por rota. As versões dos SDKs seguem o contrato: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` e `argus-client` enviam `2026.4.0` no corte GA de v2026.4. As entradas do CHANGELOG no bundle curado são versionadas da mesma forma.

Tooling: Postman, Insomnia, geradores OpenAPI

Como o descritor vive no caminho well-known RFC 8615, qualquer cliente alinhado com padrões encontra-o sem configuração à medida. Postman: importa diretamente de `https://api.knogin.com/.well-known/openapi.json`. Insomnia: o mesmo URL via `Import From URL`. Stoplight Studio, Redocly CLI e `openapi-generator-cli` resolvem o URL da mesma forma. Geradores que preferem YAML podem puxar o payload equivalente de `/.well-known/openapi.yaml`. Os parceiros programáticos começam tipicamente em `/.well-known/api-catalog`, seguem o link `service-desc` e fazem cache contra o ETag devolvido pelo well-known de OpenAPI.

Round-trip de descoberta

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

Resposta da listagem reflexiva 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": []
}

Pronto para cablar a descoberta no teu tooling?

Abre a referência de API para o contrato público curado, ou fala com a Knogin se precisares de ajuda para arrancar uma integração a partir dos endpoints well-known.