Executive Overview
IETF RFC 9727 standardizes how web origins advertise their active APIs to automated agents. Using RFC 9264 JSON Linksets at /.well-known/api-catalog, agents automatically locate OpenAPI specs, documentation endpoints, and health status without brittle scraping.
1. Understanding RFC 9727 Linksets
Traditional web APIs rely on human-oriented developer portals. RFC 9727 creates an authoritative machine surface at /.well-known/api-catalog serving application/linkset+json.
Key Link Relations:
service-desc: Direct URI to the OpenAPI / Swagger JSON schema.service-doc: Human or agent-readable documentation endpoint.status: Live health and readiness endpoint for automated retry and failover.
/.well-known/api-catalog
{
"linkset": [
{
"anchor": "https://tinycto.tv/api/episodes",
"service-desc": [
{
"href": "https://tinycto.tv/api/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://tinycto.tv/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://tinycto.tv/api/health",
"type": "application/json"
}
]
}
]
}