Network Working Group M. F. Callec Internet-Draft Independent Intended status: Informational 24 May 2026 Expires: 25 November 2026 A Well-Known URI for API Change Advisories draft-callec-api-advisory-01 Abstract This document defines a well-known URI, /.well-known/api- advisory.json, at which API providers MAY publish a machine-readable JSON discovery file. That file identifies the API and provides the URL of an Atom Syndication Format feed carrying structured change advisories. The Atom feed enables automated scanners and API consumers to discover pricing changes, deprecations, security advisories, and other relevant events without relying on manual monitoring of blogs or mailing lists. Advisory metadata is conveyed through a dedicated XML namespace defined in this document. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 25 November 2026. Copyright Notice Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Callec Expires 25 November 2026 [Page 1] Internet-Draft api-advisory May 2026 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Scope and Limitations . . . . . . . . . . . . . . . . . . 4 2. The Well-Known URI . . . . . . . . . . . . . . . . . . . . . 4 3. Discovery File Format . . . . . . . . . . . . . . . . . . . . 5 3.1. Top-Level Fields . . . . . . . . . . . . . . . . . . . . 5 3.2. Example Discovery File . . . . . . . . . . . . . . . . . 6 4. Atom Feed . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. Feed-Level Elements . . . . . . . . . . . . . . . . . . . 6 4.2. Entry-Level Elements . . . . . . . . . . . . . . . . . . 7 4.3. Localization . . . . . . . . . . . . . . . . . . . . . . 7 5. Advisory XML Namespace . . . . . . . . . . . . . . . . . . . 7 5.1. The Element . . . . . . . . . . . . . . . 8 5.1.1. Child Elements of . . . . . . . . . . 8 6. Advisory Identifier . . . . . . . . . . . . . . . . . . . . . 9 6.1. Uniqueness Scope . . . . . . . . . . . . . . . . . . . . 9 6.2. Normalization . . . . . . . . . . . . . . . . . . . . . . 9 6.3. Accepted Variants . . . . . . . . . . . . . . . . . . . . 10 6.4. Producer Recommendations . . . . . . . . . . . . . . . . 10 6.5. Reference Implementation . . . . . . . . . . . . . . . . 10 7. Pagination . . . . . . . . . . . . . . . . . . . . . . . . . 12 8. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9. Advisory Status . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Status Values . . . . . . . . . . . . . . . . . . . . . . 13 10. Priority Levels . . . . . . . . . . . . . . . . . . . . . . . 13 11. Categories . . . . . . . . . . . . . . . . . . . . . . . . . 14 12. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 12.1. Multiple Distinct APIs at the Same FQDN . . . . . . . . 15 12.2. Scope Child Elements . . . . . . . . . . . . . . . . . . 15 12.3. Level Values . . . . . . . . . . . . . . . . . . . . . . 16 12.4. Versions Element . . . . . . . . . . . . . . . . . . . . 16 12.5. Route Elements . . . . . . . . . . . . . . . . . . . . . 16 12.6. Path Pattern Syntax . . . . . . . . . . . . . . . . . . 17 12.6.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . 17 12.6.2. Matching Semantics . . . . . . . . . . . . . . . . . 18 12.6.3. Matching Examples . . . . . . . . . . . . . . . . . 18 12.7. Scope Semantics . . . . . . . . . . . . . . . . . . . . 20 13. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 13.1. Discovery File . . . . . . . . . . . . . . . . . . . . . 20 13.2. Atom Feed . . . . . . . . . . . . . . . . . . . . . . . 20 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 14.1. Well-Known URI Registration . . . . . . . . . . . . . . 23 14.2. XML Namespace Registration . . . . . . . . . . . . . . . 24 15. Security Considerations . . . . . . . . . . . . . . . . . . . 24 15.1. HTTPS Requirement . . . . . . . . . . . . . . . . . . . 24 Callec Expires 25 November 2026 [Page 2] Internet-Draft api-advisory May 2026 15.2. Namespace Validation . . . . . . . . . . . . . . . . . . 24 15.3. Feed URL Validation . . . . . . . . . . . . . . . . . . 24 15.4. Availability . . . . . . . . . . . . . . . . . . . . . . 24 15.5. Content Integrity . . . . . . . . . . . . . . . . . . . 25 15.6. Historical Record Preservation . . . . . . . . . . . . . 25 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 16.1. Normative References . . . . . . . . . . . . . . . . . . 25 16.2. Informative References . . . . . . . . . . . . . . . . . 26 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 1. Introduction API providers routinely make changes that affect their consumers: endpoints are deprecated, pricing models shift, authentication mechanisms are rotated, security vulnerabilities are disclosed. Today, this information is conveyed through provider blogs, developer mailing lists, and dashboard notifications, all of which require consumers to monitor multiple out-of-band channels and cannot be discovered programmatically. This document defines a well-known URI ([RFC8615]) at which a provider MAY publish a JSON discovery file. That file, in turn, points to an Atom feed ([RFC4287]) that carries the advisory entries. Delegating feed semantics, pagination, ordering, and syndication to Atom avoids reinventing those mechanisms and allows implementers to reuse existing Atom libraries. The advisory-specific metadata is conveyed through a dedicated XML namespace defined in Section 5. Scanners and API clients can poll the well-known URI to locate the feed, then poll the feed itself to detect changes relevant to their integration, without any prior coordination with the provider. 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 1.2. Terminology The following terms are used throughout this document. *API provider:* An entity that operates an HTTP-based service accessible at one or more FQDNs and that exposes a defined programmatic interface to external consumers. Callec Expires 25 November 2026 [Page 3] Internet-Draft api-advisory May 2026 *FQDN:* Fully Qualified Domain Name, as used in the HTTP Host header ([RFC9110]). *Advisory:* A single structured announcement published by an API provider to inform consumers of a change that affects their integration. 1.3. Scope and Limitations This document is an independent submission and does not represent IETF consensus. It is published as a pre-draft proposal to gather community feedback on the problem space and the proposed approach. 2. The Well-Known URI The well-known URI defined by this document is: /.well-known/api-advisory.json It MUST be served using HTTPS. The discovery file MUST be served from the exact FQDN on which the API being described is hosted. If the API is reachable at api.example.net, the discovery file MUST be available at: https://api.example.net/.well-known/api-advisory.json The file MUST NOT be considered authoritative for any other FQDN, including parent domains or subdomains. If the discovery file is served at api.example.net, it does not extend to v1.api.example.net, to example.net, or to any other hostname. Each FQDN requiring advisory coverage MUST host its own discovery file. +===========================+==================+===================+ | File location |Applies to |Does NOT apply to | +===========================+==================+===================+ | api.example.net/.well- |api.example.net |v1.api.example.net,| | known/api-advisory.json | |example.net | +---------------------------+------------------+-------------------+ | v1.api.example.net/.well- |v1.api.example.net|api.example.net | | known/api-advisory.json | | | +---------------------------+------------------+-------------------+ | example.net/.well-known/ |example.net |api.example.net | | api-advisory.json | | | +---------------------------+------------------+-------------------+ Table 1: FQDN scope examples Callec Expires 25 November 2026 [Page 4] Internet-Draft api-advisory May 2026 3. Discovery File Format The discovery file is a JSON object. Producers MUST serve it with the Content-Type application/json. 3.1. Top-Level Fields +==================+==========+=============+===================+ | Field | Required | Type | Description | +==================+==========+=============+===================+ | protocol_version | MUST | string | Version of this | | | | | specification | | | | | (currently "1.0") | +------------------+----------+-------------+-------------------+ | namespace | MUST | string | The FQDN this | | | | | file is | | | | | authoritative for | +------------------+----------+-------------+-------------------+ | last_updated | MUST | string | Datetime of the | | | | ([RFC3339]) | last change to | | | | | this file | +------------------+----------+-------------+-------------------+ | api_name | MUST | string | Human-readable | | | | | name of the API | +------------------+----------+-------------+-------------------+ | feed_url | MUST | string | URL of the Atom | | | | (URI) | feed carrying | | | | | advisories | +------------------+----------+-------------+-------------------+ Table 2: Discovery file top-level fields The namespace field MUST exactly match the FQDN from which the file is served, as it would appear in an HTTP Host header ([RFC9110]). Consumers MUST reject or ignore a file where namespace does not match the request host. The protocol_version field allows consumers to detect files produced by future revisions of this specification. Consumers MUST check this field before processing any other field. If the value of protocol_version is not a version the consumer implements, the consumer MUST NOT process the file and SHOULD surface an error or warning to the operator. The only version defined by this document is "1.0". Callec Expires 25 November 2026 [Page 5] Internet-Draft api-advisory May 2026 The feed_url field MUST be an absolute URI ([RFC3986]) using the https scheme. It points to an Atom feed document as defined in Section 4. The feed URL MAY be on a different FQDN than the discovery file, for example if the provider hosts its advisory feed on a dedicated infrastructure domain. 3.2. Example Discovery File { "protocol_version": "1.0", "namespace": "api.example.com", "last_updated": "2026-05-13T20:45:00Z", "api_name": "Example Payments API", "feed_url": "https://api.example.com/.well-known/api-advisory-feed.atom" } 4. Atom Feed Advisories are published as entries in an Atom Syndication Format feed ([RFC4287]). The feed MUST be served using HTTPS. Producers MUST serve the feed with the Content-Type application/atom+xml. Using Atom delegates feed semantics, ordering, and pagination to a well-understood and widely implemented standard, allowing API providers to reuse existing Atom server infrastructure and consumers to reuse existing Atom client libraries. 4.1. Feed-Level Elements The Atom element MUST include the following child elements as defined by [RFC4287]: * : A permanent, universally unique IRI identifying the feed. * : A human-readable title for the feed. * <updated>: The datetime of the most recent advisory entry, in [RFC3339] format. * <link rel="self">: The URL of the feed itself. Producers SHOULD also include <link rel="alternate"> pointing to a human-readable page about the API. Callec Expires 25 November 2026 [Page 6] Internet-Draft api-advisory May 2026 4.2. Entry-Level Elements Each advisory is represented as an Atom <entry> element. Entries MUST be ordered from most recent to oldest by <updated> value. This ordering allows consumers to stop processing the feed as soon as they encounter an entry with an <updated> value older than their last known checkpoint. Each entry MUST include: * <id>: A permanent, universally unique IRI identifying the advisory (see Section 6). * <title>: A human-readable title for the advisory. * <updated>: The datetime when the advisory was last modified. * <published>: The datetime when the advisory was first published. * <summary> or <content>: A human-readable description of the advisory. Each entry MUST also include one <api:advisory> element from the advisory namespace (Section 5) carrying structured metadata. Producers MAY include <link rel="alternate"> on each entry pointing to a full documentation page or blog post. Producers MAY include <link rel="enclosure"> on each entry for attachments such as migration guides. 4.3. Localization Atom natively supports per-element xml:lang attributes ([RFC4287], Section 2). Producers MAY provide multilingual <title> and <summary> elements by repeating those elements with distinct xml:lang attributes, following standard Atom practice. 5. Advisory XML Namespace This document defines the XML namespace: https://iana.org/api-advisory/1.0 (This namespace URI is a placeholder pending IANA registration.) In the examples in this document, the prefix api: is used for this namespace. Callec Expires 25 November 2026 [Page 7] Internet-Draft api-advisory May 2026 5.1. The <api:advisory> Element Each Atom <entry> MUST contain exactly one <api:advisory> element. This element carries the structured metadata specific to this specification. 5.1.1. Child Elements of <api:advisory> +==========================+==========+=============+==============+ | Element |Required | Type | Description | +==========================+==========+=============+==============+ | <api:id> |MUST | string | Advisory | | | | | identifier | | | | | (see | | | | | Section 6) | +--------------------------+----------+-------------+--------------+ | <api:advisory_datetime> |MUST | string | Datetime | | | | ([RFC3339]) | when first | | | | | published | +--------------------------+----------+-------------+--------------+ | <api:effective_datetime> |MUST | string | Datetime | | | | ([RFC3339]) | when the | | | | | change takes | | | | | effect | +--------------------------+----------+-------------+--------------+ | <api:status> |MUST | string | Lifecycle | | | | (enum) | status (see | | | | | Section 9) | +--------------------------+----------+-------------+--------------+ | <api:superseded_by> |MUST when | string | ID of the | | |status is | | replacing | | |superseded| | advisory | +--------------------------+----------+-------------+--------------+ | <api:category> |MUST | string | Type of | | | | (enum) | change (see | | | | | Section 11) | +--------------------------+----------+-------------+--------------+ | <api:priority> |MUST | string | Severity | | | | (enum) | level (see | | | | | Section 10) | +--------------------------+----------+-------------+--------------+ | <api:action_required> |MUST | boolean | Whether the | | | | (true/ | consumer | | | | false) | must act | +--------------------------+----------+-------------+--------------+ | <api:suggested_action> |SHOULD | string | Recommended | | | | | action | | | | | (English) | Callec Expires 25 November 2026 [Page 8] Internet-Draft api-advisory May 2026 +--------------------------+----------+-------------+--------------+ | <api:scope> |MUST | element | Affected | | | | | portion of | | | | | the API (see | | | | | Section 12) | +--------------------------+----------+-------------+--------------+ Table 3: Child elements of api:advisory 6. Advisory Identifier Advisory identifiers follow the pattern ADV-YYYY-N, where YYYY is a year and N is a positive integer sequence number. The Atom <entry><id> element MUST be a URI. Producers MUST construct this URI by appending the advisory identifier to a stable base IRI specific to their feed, for example: https://api.example.com/advisories/ADV-2026-003 The <api:id> element inside <api:advisory> carries the short-form identifier string (e.g. ADV-2026-003) for use in structured processing and cross-reference. 6.1. Uniqueness Scope Advisory IDs MUST be unique within a single advisory feed. Uniqueness is NOT required across different feeds hosted on different FQDNs. Teams managing separate FQDNs are not expected to coordinate their ID sequences. A globally unambiguous advisory is identified by the tuple (namespace, normalized_id), not by normalized_id alone. 6.2. Normalization Because the format is intentionally lenient to accommodate different producer conventions, consumers MUST normalize IDs before any comparison or deduplication. Normalization MUST follow these steps: 1. Split the raw string on the - character. The result MUST contain exactly three elements; if not, the ID is malformed and MUST be rejected. 2. Convert the first element to upper-case and verify it equals "ADV"; if not, the ID MUST be rejected as having an unknown prefix. Callec Expires 25 November 2026 [Page 9] Internet-Draft api-advisory May 2026 3. Parse the second and third elements as base-10 integers, discarding any leading zeros. If either element is not a valid integer, the ID MUST be rejected. The canonical form for storage, comparison, and deduplication is the tuple (prefix, year, seq). Two IDs are equal if and only if their normalized tuples are identical. 6.3. Accepted Variants The following raw strings all normalize to the same identity: +================+========+======+=====+ | Raw string | prefix | year | seq | +================+========+======+=====+ | ADV-2026-001 | ADV | 2026 | 1 | +----------------+--------+------+-----+ | adv-2026-001 | ADV | 2026 | 1 | +----------------+--------+------+-----+ | ADV-2026-1 | ADV | 2026 | 1 | +----------------+--------+------+-----+ | ADV-002026-001 | ADV | 2026 | 1 | +----------------+--------+------+-----+ | adv-002026-1 | ADV | 2026 | 1 | +----------------+--------+------+-----+ Table 4: Equivalent advisory ID representations 6.4. Producer Recommendations Producers SHOULD emit IDs in the form ADV-YYYY-NNN (upper-case prefix, 4-digit year, sequence number zero-padded to at least 3 digits) for human readability. This is a SHOULD, not a MUST; parsers MUST handle all valid variants. 6.5. Reference Implementation The following JavaScript functions implement normalization, equality testing, and key generation for use in deduplication structures such as Map or Set. They are provided for illustrative purposes and do not form a normative part of this specification. Callec Expires 25 November 2026 [Page 10] Internet-Draft api-advisory May 2026 /** * Parses and normalizes an advisory ID string into its three * components. The returned tuple {prefix, year, seq} MUST be used * for all comparisons (never compare raw ID strings directly). * * @param {string} id Raw advisory ID (e.g. "ADV-2026-001") * @returns {{ prefix: string, year: number, seq: number }} * @throws {Error} If the ID is malformed or contains * non-numeric segments */ function parseAdvisoryId(id) { const blocks = id.split("-"); if (blocks.length !== 3) throw new Error(`Malformed advisory ID: "${id}"`); const prefix = blocks[0].toUpperCase(); if (prefix !== "ADV") throw new Error(`Unknown prefix "${prefix}" in ID: "${id}"`); const year = parseInt(blocks[1], 10); const seq = parseInt(blocks[2], 10); if (isNaN(year) || isNaN(seq)) throw new Error(`Non-numeric segment in ID: "${id}"`); return { prefix, year, seq }; } /** * Returns true if two raw ID strings refer to the same advisory, * regardless of casing or zero-padding. */ function advisoryIdsEqual(a, b) { const pa = parseAdvisoryId(a); const pb = parseAdvisoryId(b); return pa.prefix === pb.prefix && pa.year === pb.year && pa.seq === pb.seq; } /** * Returns a stable string key suitable for use in a Map or Set. * For cross-namespace deduplication, prefix this key with the * namespace: `${namespace}::${advisoryIdKey(id)}`. * * @param {string} id Raw advisory ID * @returns {string} Canonical key, e.g. "ADV-2026-1" */ Callec Expires 25 November 2026 [Page 11] Internet-Draft api-advisory May 2026 function advisoryIdKey(id) { const { prefix, year, seq } = parseAdvisoryId(id); return `${prefix}-${year}-${seq}`; } 7. Pagination Atom natively supports feed pagination through the use of <link> elements with rel="next" and rel="prev" relation types. Producers with a large number of advisories SHOULD use these standard link relations to split the feed across multiple pages, rather than defining a custom pagination mechanism. Because entries are ordered most recent first, rel="next" points toward older entries and rel="prev" points toward more recent entries. The feed URL returned in the feed_url field of the discovery file (Section 3) MUST point to the first (most recent) page of the feed. 8. Caching Producers SHOULD set a Cache-Control header (see [RFC7234]) on the advisory feed response. A recommended value is: Cache-Control: public, max-age=3600 A max-age of less than 60 seconds is NOT RECOMMENDED, as it provides no meaningful benefit over uncached responses. Consumers SHOULD respect the Cache-Control header when polling, and SHOULD also compare the feed-level <updated> element to the value observed on their last successful fetch to determine whether the feed content has actually changed. 9. Advisory Status Each advisory MUST carry an <api:status> element indicating its current lifecycle state. Producers MUST NOT remove advisory entries from the feed once published; instead they MUST update the <api:status> element to reflect the advisory's current state and update the Atom <updated> element accordingly. This preserves the historical record and allows consumers that previously processed an advisory to detect status changes on subsequent polls. Callec Expires 25 November 2026 [Page 12] Internet-Draft api-advisory May 2026 9.1. Status Values +============+======================================================+ | Value | Meaning | +============+======================================================+ | active | The advisory is current and applicable | +------------+------------------------------------------------------+ | withdrawn | The advisory was retracted and should | | | be disregarded | +------------+------------------------------------------------------+ | superseded | The advisory has been replaced by a | | | newer one | +------------+------------------------------------------------------+ Table 5: Advisory status values When <api:status> is superseded, the <api:superseded_by> element MUST be present and MUST contain the normalized ID of the replacing advisory. The replacing advisory MUST exist within the same feed (or a subsequent page of the same paginated feed). Consumers SHOULD fetch and process the replacement advisory before acting on the superseded one. 10. Priority Levels The <api:priority> element indicates the urgency of the advisory. +==========+========================================================+ | Value | Meaning | +==========+========================================================+ | critical | Immediate action required; | | | breaking or security impact | +----------+--------------------------------------------------------+ | high | Action required before the | | | effective datetime | +----------+--------------------------------------------------------+ | medium | Action recommended; graceful | | | degradation is possible | +----------+--------------------------------------------------------+ | low | Minor or optional change | +----------+--------------------------------------------------------+ | info | No action needed; | | | informational only | +----------+--------------------------------------------------------+ Table 6: Priority values Callec Expires 25 November 2026 [Page 13] Internet-Draft api-advisory May 2026 11. Categories The <api:category> element indicates the type of change being announced. +=======================+==========================================+ | Value | Meaning | +=======================+==========================================+ | pricing_change | Free tier ending, price change, or quota | | | change | +-----------------------+------------------------------------------+ | legal_update | Terms of service, privacy policy, or | | | data residency | +-----------------------+------------------------------------------+ | compliance_update | Change imposed by an external regulation | | | (e.g. GDPR, PCI-DSS) | +-----------------------+------------------------------------------+ | deprecation | A feature or endpoint marked for future | | | removal | +-----------------------+------------------------------------------+ | sunset | A feature or endpoint being permanently | | | removed | +-----------------------+------------------------------------------+ | end_of_life | An entire API version being permanently | | | decommissioned | +-----------------------+------------------------------------------+ | breaking_change | A non-backward-compatible API change | +-----------------------+------------------------------------------+ | maintenance | Planned downtime or degraded | | | availability | +-----------------------+------------------------------------------+ | incident | An ongoing or recently resolved incident | +-----------------------+------------------------------------------+ | migration_required | Consumers must migrate to a new system | +-----------------------+------------------------------------------+ | security_advisory | Vulnerability or key rotation requiring | | | consumer action | +-----------------------+------------------------------------------+ | credential_rotation | API keys, certificates, or OAuth secrets | | | are being rotated | +-----------------------+------------------------------------------+ | performance_update | SLA or throughput limit change | +-----------------------+------------------------------------------+ | new_feature | A new endpoint or capability (non- | | | breaking) | +-----------------------+------------------------------------------+ | ownership_transfer | The API has been acquired, transferred, | | | or rebranded | Callec Expires 25 November 2026 [Page 14] Internet-Draft api-advisory May 2026 +-----------------------+------------------------------------------+ | endpoint_moved | A path or domain has changed | +-----------------------+------------------------------------------+ | rate_limit_change | Request quotas or throttling has been | | | updated | +-----------------------+------------------------------------------+ | data_retention_update | Data storage duration or policy has | | | changed | +-----------------------+------------------------------------------+ | region_change | Geographic availability has changed (new | | | region, closure, or data relocation) | +-----------------------+------------------------------------------+ Table 7: Category values 12. Scope The <api:scope> element describes which portion of the API is affected by an advisory. It uses a progressive model: a consumer can stop reading <api:scope> as soon as the <api:level> child element indicates an impact broad enough to be relevant. 12.1. Multiple Distinct APIs at the Same FQDN A single FQDN MAY host multiple distinct APIs (for example, /payments/** and /identity/**). The scope mechanism defined in this section handles this case explicitly. An advisory with <api:level>global</api:level> applies to all APIs hosted at the FQDN. An advisory with <api:level>routes</api:level> targets a specific API or set of endpoints by path prefix or explicit route list. Producers operating multiple distinct APIs at the same FQDN SHOULD use route- level scope to avoid ambiguity, and SHOULD use path prefixes that clearly identify the target API (e.g., /payments/** or /identity/**). Consumers MUST NOT assume that a global-scoped advisory applies only to the API they are currently integrating with; they SHOULD surface it as affecting the entire FQDN. 12.2. Scope Child Elements +================+====================+=========+==============+ | Element | Required | Type | Description | +================+====================+=========+==============+ | <api:level> | MUST | string | Granularity | | | | (enum) | of the scope | +----------------+--------------------+---------+--------------+ | <api:versions> | MUST when level is | element | Affected API | | | versions; MAY when | | versions | | | level is routes | | | Callec Expires 25 November 2026 [Page 15] Internet-Draft api-advisory May 2026 +----------------+--------------------+---------+--------------+ | <api:routes> | MUST when level is | element | Affected | | | routes | | routes | +----------------+--------------------+---------+--------------+ Table 8: Scope child elements 12.3. Level Values +==========+=================================================+ | Value | Meaning | +==========+=================================================+ | global | The entire FQDN is affected; <api:versions> and | | | <api:routes> are ignored | +----------+-------------------------------------------------+ | versions | Only the listed versions are affected; | | | <api:routes> is ignored | +----------+-------------------------------------------------+ | routes | Only the listed routes are affected; | | | <api:versions> is an optional additional filter | +----------+-------------------------------------------------+ Table 9: Scope level values 12.4. Versions Element When <api:level> is versions, the <api:versions> element MUST be present and MUST contain one or more <api:version> child elements. When <api:level> is routes, <api:versions> MAY be present and, if so, MUST contain one or more <api:version> child elements. Each <api:version> element MUST contain a single version identifier string as its text content. The version identifier is an opaque string and is compared case-sensitively. Producers SHOULD use the same version identifiers as those exposed in the API itself (e.g., v1, v2). 12.5. Route Elements When <api:level> is routes, the <api:routes> element MUST be present and MUST contain one or more <api:route> child elements. Each <api:route> element MUST contain: Callec Expires 25 November 2026 [Page 16] Internet-Draft api-advisory May 2026 +===============+==========+========================================+ | Child element | Required | Description | +===============+==========+========================================+ | <api:method> | MUST | HTTP method, or * to | | | | match all methods | +---------------+----------+----------------------------------------+ | <api:path> | MUST | Route path pattern | | | | (see Section 12.6) | +---------------+----------+----------------------------------------+ Table 10: Route child elements 12.6. Path Pattern Syntax The <api:path> element contains a pattern that is matched against the path component of request URIs. This section defines the syntax and matching semantics of these patterns normatively. 12.6.1. Syntax Path patterns are defined using the following ABNF grammar ([RFC5234]). The rule pchar is imported from Section 3.3 of [RFC3986] and covers unreserved characters, percent-encoded characters, sub-delimiters, colons, and at-signs. path-pattern = "/" *( segment "/" ) terminal segment = 1*pchar ; A literal path segment; no wildcards allowed. ; MUST NOT be empty. terminal = segment / wildcard-single / wildcard-multi wildcard-single = "*" ; Matches exactly one non-empty segment. wildcard-multi = "**" ; Matches one or more segments at any depth. pchar = unreserved / pct-encoded / sub-delims / ":" / "@" ; Imported from Section 3.3 of RFC 3986. A path pattern MUST begin with a / character. The empty string and patterns that do not begin with / are malformed and MUST be rejected by consumers. Callec Expires 25 November 2026 [Page 17] Internet-Draft api-advisory May 2026 Wildcards (* and **) are only permitted as an entire terminal segment; they MUST NOT appear embedded within a literal segment (e.g., /v2/web* is invalid). A pattern containing an embedded wildcard MUST be rejected by consumers. 12.6.2. Matching Semantics For the purpose of pattern matching, a subject path is split into a sequence of segments by splitting on / and discarding empty strings produced by leading, trailing, or consecutive / characters. A pattern is split into its component segments in the same way. The following rules apply: * A *literal segment* matches a subject segment if and only if the two strings are identical after percent-decoding both (case- sensitive comparison). * A ** wildcard* (wildcard-single) matches exactly one subject segment. It MUST NOT match an empty segment. It MUST NOT match across a / boundary, i.e., it matches at most one path component. * A *** wildcard* (wildcard-multi) matches one or more consecutive subject segments. It MUST NOT match zero segments. It may match segments at any depth, i.e., it consumes one or more path components including their intervening / characters. * A pattern matches a subject path if and only if the entire sequence of subject segments is consumed by the pattern segments, with no subject segments remaining after the last pattern segment is applied. Consumers MUST apply these rules deterministically. Where a ** wildcard could match a variable number of segments, it MUST be treated greedily: it consumes the maximum number of segments that still allows the overall pattern to match. In practice, because ** is only permitted as a terminal segment in this grammar, no backtracking is required. 12.6.3. Matching Examples The following table illustrates the matching rules. All examples assume case-sensitive comparison after percent-decoding. Callec Expires 25 November 2026 [Page 18] Internet-Draft api-advisory May 2026 +=============+=======================+=========+===================+ | Pattern | Subject path | Match? | Reason | +=============+=======================+=========+===================+ | /v2/ | /v2/webhooks | Yes | Exact literal | | webhooks | | | match | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/ | Yes | Trailing slash | | webhooks | | | discarded | | | | | before matching | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/123 | No | Extra segment | | webhooks | | | not covered | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/abc | Yes | * matches | | webhooks/* | | | single segment | | | | | abc | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/abc/def | No | * does not | | webhooks/* | | | match across / | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/ | No | * does not | | webhooks/* | | | match an empty | | | | | segment | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/abc | Yes | ** matches one | | webhooks/** | | | segment | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks/abc/def/ | Yes | ** matches | | webhooks/** | ghi | | multiple | | | | | segments | +-------------+-----------------------+---------+-------------------+ | /v2/ | /v2/webhooks | No | ** requires at | | webhooks/** | | | least one | | | | | segment | +-------------+-----------------------+---------+-------------------+ | /v1/** | /v1/users/123/orders | Yes | ** matches | | | | | remaining | | | | | segments | +-------------+-----------------------+---------+-------------------+ | /v1/** | /v2/users | No | Literal v1 does | | | | | not match v2 | +-------------+-----------------------+---------+-------------------+ | /v2/web* | /v2/webhooks | Invalid | Embedded | | | | | wildcard; | | | | | pattern MUST be | | | | | rejected | +-------------+-----------------------+---------+-------------------+ Callec Expires 25 November 2026 [Page 19] Internet-Draft api-advisory May 2026 Table 11: Path pattern matching examples 12.7. Scope Semantics The following normative rules apply: * When <api:level> is "global", <api:versions> and <api:routes> MUST be omitted or, if present, MUST be ignored by consumers. * When <api:level> is "versions", <api:versions> is REQUIRED; <api:routes> MUST be omitted or, if present, MUST be ignored by consumers. * When <api:level> is "routes", <api:routes> is REQUIRED; <api:versions> is OPTIONAL and, if present, acts as an additional filter: the advisory applies only to the listed routes within the listed versions. 13. Example The following example shows a complete Atom feed (first page) containing three advisories in reverse chronological order. It demonstrates: the advisory namespace; the <api:status> element including a superseded advisory; localization via xml:lang; and feed- level pagination via rel="next". 13.1. Discovery File { "protocol_version": "1.0", "namespace": "api.example.com", "last_updated": "2026-05-13T20:45:00Z", "api_name": "Example Payments API", "feed_url": "https://api.example.com/.well-known/api-advisory-feed.atom" } 13.2. Atom Feed <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:api="https://iana.org/api-advisory/1.0"> <id>https://api.example.com/advisories/feed</id> <title>Example Payments API Advisories 2026-05-13T14:00:00Z Callec Expires 25 November 2026 [Page 20] Internet-Draft api-advisory May 2026 https://api.example.com/advisories/ADV-2026-003 Deprecation of query parameter authentication (revised) Depreciation de l'authentification par parametre (revisee) 2026-05-13T14:00:00Z 2026-05-13T14:00:00Z The migration deadline has been extended to January 1, 2027. ADV-2026-003 2026-05-13T14:00:00Z 2027-01-01T00:00:00Z active deprecation high true Replace the api_key query parameter with a Bearer token. global https://api.example.com/advisories/ADV-2026-002 Deprecation of query parameter authentication Callec Expires 25 November 2026 [Page 21] Internet-Draft api-advisory May 2026 Depreciation de l'authentification par parametre de requete 2026-05-13T09:00:00Z 2026-05-13T14:00:00Z Authentication via the api_key query parameter is deprecated. ADV-2026-002 2026-05-13T09:00:00Z 2026-10-01T00:00:00Z superseded ADV-2026-003 deprecation medium true Migrate to the Authorization HTTP header. global https://api.example.com/advisories/ADV-2026-001 Webhooks endpoint moving to paid model 2026-05-10T10:00:00Z 2026-05-10T10:00:00Z Webhook usage will be billed at $0.01 per call. ADV-2026-001 Callec Expires 25 November 2026 [Page 22] Internet-Draft api-advisory May 2026 2026-05-10T10:00:00Z 2026-12-01T00:00:00Z active pricing_change high true Review your webhook usage and update your billing plan. routes v2 POST /v2/webhooks * /v2/webhooks/** The HTTP response for the feed SHOULD include: Cache-Control: public, max-age=3600 14. IANA Considerations 14.1. Well-Known URI Registration This document requests the registration of the following well-known URI in the "Well-Known URIs" registry established by [RFC8615]: * URI suffix: api-advisory.json * Change controller: IETF Callec Expires 25 November 2026 [Page 23] Internet-Draft api-advisory May 2026 * Specification document: this document * Related information: The resource is a JSON discovery object as defined in Section 3, pointing to an Atom feed as defined in Section 4. 14.2. XML Namespace Registration This document requests the registration of the following XML namespace: * URI: https://iana.org/api-advisory/1.0 * Registrant Contact: the author of this document * XML: None; the namespace does not have an associated schema at this time. 15. Security Considerations 15.1. HTTPS Requirement Consumers MUST only fetch discovery files and advisory feeds over HTTPS. A file or feed served over plain HTTP is subject to manipulation in transit and MUST NOT be trusted. 15.2. Namespace Validation Consumers MUST verify that the namespace field in the discovery file exactly matches the FQDN from which the file was retrieved. Failure to do so may allow a malicious party to serve a discovery file for a different domain, causing consumers to subscribe to an advisory feed for the wrong API. 15.3. Feed URL Validation Consumers MUST verify that the feed_url value uses the https scheme before fetching the feed. Consumers SHOULD also verify that the feed URL is not a redirect to a non-HTTPS location. 15.4. Availability A discovery file or advisory feed that is temporarily or permanently unavailable MUST be treated as a transient error. Consumers MUST NOT interpret the absence of a discovery file or feed as confirmation that no advisories exist. Producers SHOULD ensure that both the discovery and feed endpoints are subject to the same availability guarantees as their API. Callec Expires 25 November 2026 [Page 24] Internet-Draft api-advisory May 2026 15.5. Content Integrity This specification does not define a mandatory mechanism for signing advisory feeds. Consumers relying on advisory content for automated decisions (e.g., automated circuit-breaking) SHOULD consider whether additional integrity guarantees are appropriate for their threat model. One approach is HTTP Message Signatures ([RFC9421]), which allows producers to sign HTTP responses (including the advisory feed response) using asymmetric keys. Consumers can then verify the signature before processing the feed content, without relying solely on HTTPS for authenticity. 15.6. Historical Record Preservation Producers MUST NOT remove advisory entries from the feed after they have been published. Removing a superseded or withdrawn entry may cause consumers that had previously observed it to re-process it as a new advisory on a subsequent poll, depending on their deduplication implementation. 16. References 16.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC4287] Nottingham, M., Ed. and R. Sayre, Ed., "The Atom Syndication Format", RFC 4287, DOI 10.17487/RFC4287, December 2005, . [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, . Callec Expires 25 November 2026 [Page 25] Internet-Draft api-advisory May 2026 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . 16.2. Informative References [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, DOI 10.17487/RFC7234, June 2014, . [RFC9421] Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, . Acknowledgements The author would like to thank Dale R. Worley for his review and feedback on the mailing list, in particular for suggesting the use of Atom ([RFC4287]) as the advisory delivery mechanism. Author's Address Mateo Florian Callec Independent France Email: mateo@callec.net Callec Expires 25 November 2026 [Page 26]