]> Independent

France mateo@callec.net

Applications and Real-Time Network Working Group well-known API advisory change management JSON Atom 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.

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 () at which a provider MAY publish a JSON discovery file. That file, in turn, points to an Atom feed () 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 . 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.

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 when, and only when, they appear in all capitals, as shown here.

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. FQDN: Fully Qualified Domain Name, as used in the HTTP Host header (). Advisory: A single structured announcement published by an API provider to inform consumers of a change that affects their integration.

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.

The Well-Known URI The well-known URI defined by this document is:

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:

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-known/api-advisory.json api.example.net v1.api.example.net, example.net v1.api.example.net/.well-known/api-advisory.json v1.api.example.net api.example.net example.net/.well-known/api-advisory.json example.net api.example.net

Discovery File Format The discovery file is a JSON object. Producers MUST serve it with the Content-Type application/json.

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 last change to this file api_name MUST string Human-readable name of the API feed_url MUST string (URI) URL of the Atom feed carrying advisories The namespace field MUST exactly match the FQDN from which the file is served, as it would appear in an HTTP Host header (). 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". The feed_url field MUST be an absolute URI () using the https scheme. It points to an Atom feed document as defined in . 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.

Example Discovery File

Atom Feed Advisories are published as entries in an Atom Syndication Format feed (). 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.

Feed-Level Elements The Atom <feed> element MUST include the following child elements as defined by : <id>: A permanent, universally unique IRI identifying the feed. <title>: A human-readable title for the feed. <updated>: The datetime of the most recent advisory entry, in 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.

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 ). <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 () 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.

Localization Atom natively supports per-element xml:lang attributes (, Section 2). Producers MAY provide multilingual <title> and <summary> elements by repeating those elements with distinct xml:lang attributes, following standard Atom practice.

Advisory XML Namespace This document defines the XML namespace:

(This namespace URI is a placeholder pending IANA registration.) In the examples in this document, the prefix api: is used for this namespace.

The <api:advisory> Element Each Atom <entry> MUST contain exactly one <api:advisory> element. This element carries the structured metadata specific to this specification.

Child Elements of <api:advisory> Element Required Type Description <api:id> MUST string Advisory identifier (see ) <api:advisory_datetime> MUST string () Datetime when first published <api:effective_datetime> MUST string () Datetime when the change takes effect <api:status> MUST string (enum) Lifecycle status (see ) <api:superseded_by> MUST when status is superseded string ID of the replacing advisory <api:category> MUST string (enum) Type of change (see ) <api:priority> MUST string (enum) Severity level (see ) <api:action_required> MUST boolean (true/false) Whether the consumer must act <api:suggested_action> SHOULD string Recommended action (English) <api:scope> MUST element Affected portion of the API (see )

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:

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.

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.

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: Split the raw string on the - character. The result MUST contain exactly three elements; if not, the ID is malformed and MUST be rejected. Convert the first element to upper-case and verify it equals "ADV"; if not, the ID MUST be rejected as having an unknown prefix. 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.

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

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.

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.

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 () MUST point to the first (most recent) page of the feed.

Caching Producers SHOULD set a Cache-Control header (see ) on the advisory feed response. A recommended value is:

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.

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.

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 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.

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

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 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)

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.

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.

Scope Child Elements Element Required Type Description <api:level> MUST string (enum) Granularity of the scope <api:versions> MUST when level is versions; MAY when level is routes element Affected API versions <api:routes> MUST when level is routes element Affected routes

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

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).

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: Child element Required Description <api:method> MUST HTTP method, or * to match all methods <api:path> MUST Route path pattern (see )

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.

Syntax Path patterns are defined using the following ABNF grammar (). The rule pchar is imported from Section 3.3 of and covers unreserved characters, percent-encoded characters, sub-delimiters, colons, and at-signs.

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. 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.

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.

Matching Examples The following table illustrates the matching rules. All examples assume case-sensitive comparison after percent-decoding. Pattern Subject path Match? Reason /v2/webhooks /v2/webhooks Yes Exact literal match /v2/webhooks /v2/webhooks/ Yes Trailing slash discarded before matching /v2/webhooks /v2/webhooks/123 No Extra segment not covered /v2/webhooks/* /v2/webhooks/abc Yes * matches single segment abc /v2/webhooks/* /v2/webhooks/abc/def No * does not match across / /v2/webhooks/* /v2/webhooks/ No * does not match an empty segment /v2/webhooks/** /v2/webhooks/abc Yes ** matches one segment /v2/webhooks/** /v2/webhooks/abc/def/ghi Yes ** matches multiple segments /v2/webhooks/** /v2/webhooks No ** requires at 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

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.

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

Discovery File

Atom Feed

https://api.example.com/advisories/feed 2026-05-13T14:00:00Z https://api.example.com/advisories/ADV-2026-003 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 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 2026-05-10T10:00:00Z 2026-05-10T10:00:00Z

Webhook usage will be billed at $0.01 per call.

ADV-2026-001 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:

IANA Considerations

Well-Known URI Registration This document requests the registration of the following well-known URI in the "Well-Known URIs" registry established by : URI suffix: api-advisory.json Change controller: IETF Specification document: this document Related information: The resource is a JSON discovery object as defined in , pointing to an Atom feed as defined in .

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.

Security Considerations

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.

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.

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.

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.

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 (), 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.

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.

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This document specifies Atom, an XML-based Web content and metadata syndication format. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. This document describes a mechanism for creating, encoding, and verifying digital signatures or message authentication codes over components of an HTTP message. This mechanism supports use cases where the full HTTP message may not be known to the signer and where the message may be transformed (e.g., by intermediaries) before reaching the verifier. This document also describes a means for requesting that a signature be applied to a subsequent HTTP message in an ongoing HTTP exchange.

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 () as the advisory delivery mechanism.