Zusammenfassung

  • RFC 9727 definiert /.well-known/api-catalog und die Link-Relation api-catalog, damit ein Herausgeber eine API-Sammlung erklären kann. Eigentum, Berechtigung, Erreichbarkeit, Überwachung und Zustand einzelner Ziele werden nicht attestiert.
  • Stamm-, Fremd- und Unterkataloge besitzen jeweils eigene Herausgeber, Kontexte, Caches und Aktualisierungszeiten. Ihre Topologie ist ein Graph datierter Aussagen, keine automatische Vertrauenskette.
  • Das Löschen eines item belegt eine Publikationsänderung. Für eine belastbare Stilllegung fehlen weiterhin Expositions-, Verkehrs-, Abhängigkeits-, Ausführungs-, Rückroll- und Nachbeobachtungsnachweise.

Der Eintrag kann vor dem Endpunkt verschwinden

Der im Februar 2025 auf dem IETF Standards Track veröffentlichte RFC 9727 ist bewusst klein. Ein Herausgeber antwortet unter /.well-known/api-catalog, kann per Link darauf hinweisen und liefert Linkset JSON. item listet APIs; api-catalog verweist auf weitere Kataloge.

Das hilft, weil API-Wissen oft über Deployment-Dateien, Gateways, Portale und private Tabellen verteilt ist. Der gemeinsame Einstieg macht daraus eine maschinenlesbare Aussage. Er macht die Aussage nicht zur vollständigen Kopie des laufenden Bestands.

RFC 8288 beschreibt typisierte Beziehungen, keine Betriebszertifikate. Ein gültiges item beweist weder DNS-Auflösung aus einem bestimmten Netz noch einen Listener, Eigentum, akzeptierte Zugangsdaten oder eine erfolgreiche Fachtransaktion. Ein nicht gelisteter Listener bleibt ebenfalls real.

OWASP API9:2023 ordnet alte Versionen, undokumentierte Hosts und unklare Umgebungen als Angriffsflächenrisiko ein. RFC 9727 kann diese Blindheit verringern. Wer nur Links zählt, erzeugt allerdings eine ordentlichere Form falscher Sicherheit.

Autorität gilt nicht automatisch für das Linkziel

Auch ein Katalog unter der eigenen Domain kann Partnerdienste, Managed Services, Regionen oder historische Pfade enthalten. Belegt ist die Entscheidung des Herausgebers, diese Beziehung zu publizieren. Betrieb und Änderungsbefugnis des Ziels brauchen eigene Nachweise.

Kann der Herausgeber die well-known Ressource nicht hosten, darf er laut RFC 9727 auf eine andere Domain zeigen. Discovery-Antwort, Redirects, TLS-Identitäten, Zeitpunkte und Inhalts-Hash bilden dann die Publikationskette. Ein unveränderter Titel reicht nicht, um Autoritätskontinuität zu behaupten.

Unterkataloge vervielfachen diese Grenze. Konzern, Produkt und Region können getrennte Betreuer und Veröffentlichungszyklen haben. RFC 9264 verlangt expliziten Kontext, weil ein Linkset ohne seinen Anchor eine andere Aussage bekommen kann. Die Hierarchie ist ein Graph datierter Kanten.

Ein Katalogbeleg sollte Domain, Pfad, Redirects, TLS-Gegenstelle, Antwortzeit, Medientyp, Profile, ETag oder Last-Modified, Body-Hash und jedes Kontext–Ziel–Relations-Tripel erhalten. Erste und letzte Beobachtung sind keine automatisch bekannten Erstellungs- und Löschzeiten. Das ist ein Analysevorschlag, keine zusätzliche RFC-Pflicht.

Cache-Uhr und Betriebsuhr laufen getrennt

RFC 9111 trennt Frische, Revalidierung und veraltete Antworten. Ein ETag zeigt gleiche Repräsentationen zwischen Prüfungen, nicht den Dauerbetrieb der gelisteten APIs. Lange Frische kann eine dringende Löschung verzögern; kurze Frische korrigiert keine schlecht gepflegte Quelle.

Getrennt gehören Herausgeberabsicht, Origin-Antwort, Cache-Prüfung oder Wiederverwendung, Gateway-Änderung und Beobachtungszeit. „Um 14 Uhr nicht im Katalog“ ist mit Antwort und Cache-Pfad überprüfbar. „Um 14 Uhr abgeschaltet“ folgt daraus nicht.

RFC 9727 empfiehlt, Verfügbarkeit und Leistung des Katalogs zu überwachen, Abrufe mit späteren API-Anfragen zu korrelieren, veraltete Einträge zu entfernen, Syntax und Geschäftsregeln zu prüfen und Aktualisierungen in Releases einzubetten. Entscheidend: Der Katalog ergänzt ein API-Management-Framework, ersetzt es nicht.

Ein gesunder Katalog kann eine kranke API beschreiben

Ein Monitor kann den Katalog laden, JSON validieren und jede Unterebene erreichen, während ein item fehlschlägt. Umgekehrt kann der Katalog ausfallen, während bekannte API-Adressen funktionieren. Die status-Relation aus RFC 8631 lokalisiert Statusinformationen, verschmilzt aber Statusseite, Katalog und Transaktion nicht. TCP-Verbindung, HTTP-Antwort und authentifizierter Geschäftsvorgang sind verschiedene Beobachtungen.

RFC 9727 warnt außerdem vor der Offenlegung interner APIs. TLS, Review, minimale Schreibrechte, Rate Limits und Zugriffsschutz sichern die Publikation. Sie beweisen nicht, dass ein internes Ziel von außen unerreichbar ist. Leserecht am Katalog ist auch keine Nutzungsberechtigung.

Karte löschen, Socket behalten

Eine Katalogprüfung kann Zombie-APIs finden: unbetreute, unüberwachte oder ungepatchte Schnittstellen. Sie existieren, weil Verwaltung und laufendes System auseinanderliegen. Der Fund startet die Stilllegung, er bestätigt sie nicht.

Ein item kann wegen Korrektur, Verlagerung, Verbergen, Ersatz oder geplanter Stilllegung verschwinden. Das schließt keinen Listener, widerruft kein Secret, löscht kein DNS, leert keine Queue und migriert keinen unbekannten Client. Fortgesetzte Listung belegt ebenso wenig Support.

Ein Stilllegungsbeleg verbindet letzten Snapshot und autorisierte Entscheidung mit DNS-, Routing-, Load-Balancer- und Gateway-Änderungen; betroffenen Umgebungen; Besitzern und abhängigen Jobs; Verkehr samt Messfenster und Lücken; Zugangsdaten und Datenflüssen; Ausführungsbestätigung; Ausnahme- und Rückrollverantwortung; anschließenden Probes. Ein Quartalsjob außerhalb des Fensters bleibt unbekannt statt null.

Die bestehende BTW-Analyse zu Deprecation und Sunset behandelt Client-Migration. Hier geht es enger um Katalogtopologie: Eine entfernte Relation ist kein Ausführungsbeleg. Der Server kann danach weiter antworten oder vor der Link-Löschung verschwinden. Diese Differenz ist Evidenz.

Quellen

Spezifikationen und Register: RFC 9727, RFC Editor, IETF Datatracker, IANA well-known, IANA Link Relations, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Zugeordneter Analyserahmen: Lu Heng, Note 64, Vorrang laufenden Codes, BTWs Realitätsauftrag.