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

Discovery i governance

Argus publikuje publiczną powierzchnię API poprzez discovery zgodne ze standardami: deskryptor OpenAPI 3.1 pod ścieżką well-known RFC 8615 (JSON i YAML), link-set RFC 9727 wskazujący na każdy artefakt czytelny maszynowo, refleksyjne, świadome tenanta listowanie schematów danych dostępnych dla wywołującego oraz nagłówki Sunset i Deprecation RFC 8594, dzięki którym partnerzy planują migracje tak samo jak przy każdym API opartym na otwartych standardach.

Deskryptory well-known OpenAPI

`GET /.well-known/openapi.json` oraz `GET /.well-known/openapi.yaml` udostępniają wyselekcjonowany publiczny kontrakt OpenAPI 3.1 pod ścieżką well-known RFC 8615. Oba endpointy nie wymagają uwierzytelnienia, zwracają silne ETagi pochodzące z hasha treści i honorują `If-None-Match` z `304 Not Modified`, by tooling mógł agresywnie cache’ować. Deskryptor jest filtrowany przez publiczną denylistę z `app/core/public_contract_filter.py`, która odzwierciedla tablicę `denylist` w kontrakcie strony: trasy wewnętrzne, admin i platformowe nigdy się nie pojawią. Oba formaty są semantycznie tożsame; różni je tylko serializacja.

Link-set katalogu API

`GET /.well-known/api-catalog` zwraca link-set RFC 9727, dzięki czemu partnerzy odkrywają każdy artefakt maszynowo czytelny z jednej kotwicy. Każda pozycja ogłasza `service-desc` (URI well-known JSON i YAML OpenAPI), `service-doc` (publikowaną witrynę dokumentacji) oraz `service-meta` (well-known klucza weryfikacji provenance ML-DSA-65 z `rel="provenance-verify-keys"`). Content-Type to `application/linkset+json`. Używaj go jako endpointu rozruchowego: jeden fetch dostarcza wystarczająco URI, by napędzić resztę integracji.

Refleksyjne listowanie schematów

`GET /v1/discovery/data-schemas` to refleksyjne, świadome tenanta listowanie schematów JSON, które wywołujący może teraz osiągnąć. Wymaga scope’u `argus:discovery:read` na bearer tokenie. Wyniki są filtrowane po `tenant_id` i `organization_id` z kontekstu auth oraz ograniczane przez clearance `secrecy_level` wywołującego. Opcjonalne `include_federated=true` rozszerza listę o źródła upstream dostępne kanałami zatwierdzonymi w ramach Communities of Interest (COI); opcjonalne `secrecy_max=` ogranicza wyniki do poziomu clearance’u. Każdy wpis ogłasza kanoniczne `schema_url` pod `/.well-known/schemas/{id}.json` do offline’owego pinowania kontraktu. Każde wywołanie emituje zdarzenie audytu `discovery.schemas.read`.

Nagłówki Sunset i Deprecation

Argus automatycznie emit nagłówki RFC 8594 `Sunset` i `Deprecation` na każdej trasie wymienionej w `deprecation-matrix.json`. Oba pola to znaczniki czasu IMF-fixdate (`Sun, 06 Nov 2026 08:49:37 GMT`). Towarzyszący `Link: <successor-version-url>; rel="successor-version"` wskazuje następcę, dzięki czemu tooling klienta pokazuje ścieżkę migracji bez czytania changelogu. Brak opt-inu: middleware działa jednolicie, więc wystarczy podpiąć jeden check nagłówka w kliencie HTTP, by ostrzec operatorów na długo przed datą sunset.

Jak partnerzy śledzą wersje kontraktu

Opublikowana wersja kontraktu jest w polu `info.version` OpenAPI pod `/.well-known/openapi.json` (obecnie `2026.4.0`) oraz w kontrakcie strony pod `externalContract.version`. Matryca deprecation jest partycjonowana po wersji kontraktu, więc jeden `GET` na well-known plus weryfikacja nagłówka na live request daje zarówno opublikowaną powierzchnię, jak i okna migracyjne per-route. Wersje SDK śledzą kontrakt: `@argus/connector-sdk`, `argus-connector-sdk`, `@argus/client` i `argus-client` wszystkie wydają `2026.4.0` dla cięcia GA v2026.4. Wpisy CHANGELOG w wyselekcjonowanym bundle’u są wersjonowane tak samo.

Narzędzia: Postman, Insomnia, generatory OpenAPI

Ponieważ deskryptor żyje pod ścieżką well-known RFC 8615, każdy klient zgodny ze standardami znajdzie go bez specjalnej konfiguracji. Postman: importuj wprost z `https://api.knogin.com/.well-known/openapi.json`. Insomnia: ten sam URL w `Import From URL`. Stoplight Studio, Redocly CLI oraz `openapi-generator-cli` rozwiązują URL identycznie. Generatory preferujące YAML mogą pobrać równoważny payload z `/.well-known/openapi.yaml`. Programatyczni partnerzy zwykle zaczynają od `/.well-known/api-catalog`, podążają za linkiem `service-desc`, a następnie cache’ują względem ETagu zwracanego przez well-known OpenAPI.

Round-trip 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"

Odpowiedź refleksyjnego listowania schematów

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

Gotów podpiąć discovery do swojego toolingu?

Otwórz referencję API dla wyselekcjonowanego publicznego kontraktu lub porozmawiaj z Knogin, jeśli potrzebujesz pomocy w starcie integracji z endpointów well-known.