]>

cxres+ietf@protonmail.com

Web and Internet Transport Building Blocks for HTTP APIs event query notification Events Query is a minimal protocol built on top of HTTP that allows user agents to receive event notifications directly from any resource of interest. It uses the QUERY method [RFC10008] to request (optionally) the current representation and subsequent event notifications within a single response. The Events Query Protocol (EQP) is predicated on the idea that the most intuitive source for event notifications is the resource itself. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Building Blocks for HTTP APIs Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction HTTP was originally designed as a stateless, request/response protocol for transferring hypermedia documents on the web (). This design was adequate for web pages that were mostly static and written by hand. But web applications have evolved over time to provide increasingly dynamic and interactive experiences, requiring near-instantaneous updates. HTTP does not automatically inform clients of changes to a resource. Developers have employed various techniques, such as Comet and Server-Sent Events (, Section 9.2) to work around this constraint, but these can be suboptimal for many applications. For this reason, web programmers often prefer implementing custom messaging systems over alternate protocols such as WebSocket and WebSub . Not only does this approach require additional layers of code, involving multiple Web APIs and/or userland libraries such as socket.io, it demands extra coordination effort to synchronize representation and notifications across multiple protocols. The dual-protocol approach thus compounds the development and maintenance overhead. Furthermore, deployment at scale is challenging with the notifications traffic now opaque to network intermediaries. With the rise of AIs, autonomous agents acting on behalf of a user have emerged as a significant class of consumer. Agents often need to observe HTTP resources, to monitor the outcome of prior actions and trigger new ones. But the friction involved in observing a resource an agent is already interacting with makes existing mechanisms a poor fit for such agentic workflows. Events Query is a minimal protocol built on top of the Hypertext Transfer Protocol that allows applications to request event notifications directly from a resource of interest using the QUERY method (). The objective of this specification is to make the request and receipt of event notifications extremely convenient for consumers. Events Query allows programmers to incorporate real-time functionality in their web applications without the need to switch to another protocol. Further, Events Query can deliver representation and notifications from a resource in a single response, obviating any need for coordination and saving on unnecessary round trips. With the help of a suitable composite media type parser, Events Query responses can be consumed with just a few lines of code, as illustrated in the JavaScript example below:

Events Query fetch example

Unlike other event notification mechanisms, Events Query supports content negotiation for notifications, just like representations. Thus, the Events Query Protocol preserves the flexibility of interaction afforded by HTTP and extends it to event notifications. When combined with suitable data synchronization technologies like Conflict Free Replicated Data Types (CRDT) or Operational Transforms (OT), event notifications can be used to create "live" representations. This can immensely simplify the task of programming multi-author distributed real-time applications.

Design Events Query is predicated on a resource itself being the most intuitive source for events on it. Events Query treats notifications as a response to a query for an event occurring on the resource. With HTTP allowing representations to provide a potentially unbounded stream of data, the Events Query Protocol is also able to communicate multiple events on the resource as a stream of notifications.

Goals To aid the development of real-time applications, it is imperative that the Events Query Protocol reduces the complexity of both servers and clients implementing event notifications. With this in mind, the goals of the Events Query Protocol are:

1. to serve event notifications using the Hypertext Transfer Protocol . Clients already fetching resources over HTTP need not switch to another protocol for receiving event notifications.
2. to send updates directly from a resource of interest, obviating the need for additional resources to be specifically dedicated as notification endpoints. In contrast to existing approaches, this frees up the client from the burden of coordinating the response from the resource of interest with notifications from an endpoint.
3. to provide reliable and in-order transfer of event notifications. The transfer of notifications directly from a resource ensures this for the duration of the response stream. Recovery across errors and loss of connection can be layered (see ).
4. to deliver the representation and notifications in response to a single request, minimizing round trips between clients and servers. It also eliminates the need to synchronize the delivery of the representation and notifications.
5. to enable the transfer of event notifications using arbitrary formats that might be content-negotiated. This allows implementers to serve notifications that are more expressive, say, in comparison to existing HTTP-based messaging protocols such as Server-Sent Events (, Section 9.2).
6. to specify transparent notification semantics that empower intermediaries to scale event notifications, improve reliability and reduce latency. Intermediaries shall also be able to proactively update caches in real-time.

Constraints To the extent feasible, the Events Query:

1. adheres to established practices and conventions. In particular, every attempt has been made to reuse existing protocols and specifications. Implementers shall be able to repurpose existing tools and libraries for implementing this specification.
2. conforms to , best practices for , and . This specification can thus be used to extend the capabilities of any existing or future resource to additionally serve event notifications over HTTP. This is to afford implementers the opportunity to scale notifications with their data and application.

Scope Events Query specifies a minimal protocol surface for transferring notifications over HTTP that includes:

1. A mechanism to discover support for Events Query on a resource ().
2. A mechanism to request event notifications from a resource (Sections and ) along with the representation ().
3. An abstract data model for requesting event notifications ().
4. Response semantics for a single notification.
5. Response semantics for a stream carrying the representation (if requested) and multiple event notifications.

Out of Scope

Event Semantics Implementations require flexibility to generate event notifications for the applications they wish to support on any given resource. It follows that the Events Query Protocol does not specify event semantics, including:

1. The events for which a notification might be generated.
2. The content of an event notification.

Implementations can further provide mechanisms to filter the events generating notifications or to select the content of notifications. Affordances for such mechanisms can be exposed to clients by extending the abstract with additional specifications.

Realizations and Formats Since transferred data is subject to content negotiation between clients and server, the Events Query Protocol does not commit to a specific:

1. Realization of the abstract data model () used for requesting event notifications.
2. Representation for the response stream encapsulating multiple event notifications.
3. Form of event notifications within the response stream.

Temporal Coordination Event notifications are typically implemented along with temporal coordination mechanisms, ranging in complexity from resumability on reconnection to real-time state synchronization. Implementations adopt these mechanisms based on application requirements. For this reason, the Events Query Protocol itself does not specify temporal coordination across responses. Instead, implementations shall be able to extend the with additional specifications that provide:

1. A scheme for versioning events occurring on a resource.
2. Replay or resumption of event notifications from a prior event. This can, for example, help clients recover upon reconnection without refetching the representation.
3. Identification of resource representations, separate from event notifications, within the response stream. This is useful for a first fetch before a client starts receiving notifications or for periodic reconciliation during state synchronization.
4. The Conflict-free Replicated Data Types (CRDT) or Operational Transforms (OT) strategy to be implemented by a client for synchronizing the representation using event notifications.

Limitations Events Query only allows notifications to be sent for events on a given resource. To transfer event notifications originating from multiple resources in a single response, implementations will need to mint additional resources to serve as notification endpoints. This is no different from APIs built on top of existing messaging protocols (see, for example, WebSocket and WebSub ). Browsers cap the number of persistent HTTP/1.1 connections per host, limiting the suitability of Events Query for web applications in the browser that require simultaneous event notifications from multiple resources on the same host. This limitation is identical to that of other HTTP-based streaming protocols, such as Server-Sent Events (, Section 9.2). Implementations are strongly encouraged to adopt HTTP/2 (or later). HTTP/1.1 servers might consider setting up a reverse proxy over HTTP/2 (or later) or implement mitigation strategies, such as, maximizing the number of concurrent connections and providing alternate hosts for resources. Implementations might alternatively consider using endpoints to provide event notifications for multiple resources as previously described. Clients on a browser requesting event notifications over an HTTP/1.1 connection are advised to exercise caution when simultaneously opening multiple persistent connections to a given host.

Comparison with Server-Sent Events At the time of writing, Server-Sent Events (SSE) has emerged as the de facto mechanism for transferring event notifications over HTTP. Server-Sent Events is standardized as part of HTML Living Standard by the WHATWGAs of October 2022, HTML Living Standard maintainer Anne van Kesteren has stated that WHATWG does not intend to extend the EventSource API, with reasons for the decision cited in a subsequent comment. through the EventSource API (, Section 9.2.2) on user agents and the text/event-stream media type (, Section 17.7) to transmit event notifications. This approach is fundamentally inconsistent with terminology defined in HTTP Semantics (), transferring a sequence of asynchronous messages instead of a representation "intended to reflect a past, current, or desired state of a given resource". Practically, the text/event-stream media type being limited to only textual content forces developers to opt for alternative protocols such as WebSockets , despite the increased complexity. The EventSource API does not even allow for headers to be sent with requests. This has led to a proliferation of non-standard implementations of Server-Sent Eventssuch as this, this, this, this, this and this that provide support for custom headers, such as for sending credentials, or use the POST method to communicate additional configuration in the request body. Events Query takes a principled approach to event notifications, as established in . In particular, the definition of an event notification as a "representation" of event(s) () admits the use of arbitrary media types for event notifications. Clients can use content negotiation as well as preconditions in a subscription request. Further, Events Query not only lets clients receive both the representation and notifications over the same protocol, viz. HTTP, but these can be encapsulated within a single HTTP response. Clients do not need to, say, authenticate multiple times, possibly with different mechanisms, to obtain data that is logically from the same resource. Clients also do not have to coordinate and synchronize multiple response streams carrying a representation and notifications from the same effective resource.

Conformance

Document Conventions All examples and notes in this specification are non-normative.

Requirements Notation 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 and Core Concepts

Event An event is the instantaneous effect of the (normal or abnormal) termination of the invocation of an operation on an object of interest . The entity invoking an operation is termed the invoker. In the specific context of HTTP, the object of interest is data scoped to some resource. When the operation is an HTTP method, the invoker is a user agent. However, an operation need not be limited to an HTTP method; it might just as easily have been invoked using another mechanism or protocol. Events are then an extension of resource state (see ) in the temporal dimension.

Observation An event is considered observable, if an entity outside the invoker and object of interest can detect its occurrence . This entity is the observer. It follows from the HTTP uniform interface that the observer is always a server. The events that are observed, the mechanism of observation, and information recorded from the event are implementation details for the server. That an origin server has to assume the role of an observer in order to generate event notifications is obvious. An intermediary, while not observing the data scoped to a resource directly, still has the possibility to serve as an observer. An intermediary can observe events transmitted by an origin server or another intermediary, whether using Events Query or another mechanism, to generate event notifications for outbound consumers.

Event Notification An event notification, or notification, is information transmitted by an observer upon an event or contiguous events on a resource. Events Query extends "information hiding" behind the HTTP uniform interface to the temporal dimension by defining communication with respect to a transferable notification of the resource event(s), rather than transferring the event(s) themselves. A target resource might be capable of generating multiple notifications for the same event(s) that a subscriber can select from using content negotiation. Hypertext notifications can not only provide information about the resource events but also processing instructions that help guide the recipient's future actions, for example, the possibility to determine the current representation from a previous representation.

Subscription A subscription is an expression of interest to receive event notifications sent to an observer. The requesting entity is a subscriber. Due to the request/response semantics of HTTP, the subscriber coincides with the recipient of event notifications ( uses the term requester or broker to identify a requesting entity, with the broker and recipient together forming the subscriber; for this specification, the distinction is not necessary). The subscription in the form of a query affords the user agent the opportunity to engage in content negotiation for preferred form of event notifications (as well as the representation, if simultaneously requested).

Events Header Field "Events" is a Dictionary structured header field () to communicate the properties of a response stream to an Events Query. In a request, the Events header field allows a client to indicate its preferences for the properties of the response stream carrying event notifications. The Events header field is not meant for content negotiation. In a response, the Events header field allows a server to specify the properties of a response stream carrying event notifications. The order of keys in the Events header field is insignificant. Senders SHOULD NOT generate keys not registered with the HTTP Events Field Registry (the exception is only for experimentation). Recipients MAY ignore keys that they are unaware of.

duration Property The "duration" property is an Integer () or Decimal () valued Dictionary key specified on the Events header field to communicate the response duration in seconds. Only non-negative values are valid. In a request, the duration property indicates the duration for which a client wants to receive event notifications. A value of 0 indicates that the client does not have a preference for the response duration. A server MAY ignore this property. In a response, the duration property specifies the maximum duration for which a server intends to serve event notifications. This property is merely advisory, and a server MAY end the response before this duration. A server SHOULD NOT set a response duration longer than the period for which an authorization is valid. This is to ensure that a server does not send notifications to clients after their authorization expires, while accommodating valid authorizations where the server is unable to determine the authorization period in advance. Once the request's authorization expires or is revoked, the server MUST NOT send any more notifications. A sender MUST conform to these stipulations when generating the duration property. If the value of the duration property fails to conform to these stipulations, it MUST be ignored by the recipient.

Subscription Data Model The abstract data model specifies the semantics of an Events Query. A realization of the data model allows a client to specify in a subscription request:

• an interest in receiving a stream of event notifications from a resource in a preferred form.
• an interest in receiving a representation of a resource in a preferred form.

Implementations can choose appropriate media types to realize the subscription data model. Implementations are free to extend the data model to include additional data. A specific realization of the data model is beyond the scope of this specification (see ). The following example shows the body of a subscription request wherein the state and events properties are used to specify request headers for representation and event notifications respectively in a YAML-like syntax.

Events Query Data Model in a YAML-like syntax

Discovery A user agent can discover if a server enables Events Query on a resource by examining support for query with a media type that can realize the . A server MUST advertise media types accepted for Events Query using the Accept-Query header field () in a response.

Discovery Request

Discovery Response

Single Notification The simplest Events Query is to request a notification for the next event(s) on a resource. This, in effect, adds long polling capability () to a resource.

Request To receive a single notification, a client MUST:

• send a realization of the subscription data model that does not include an interest in receiving a stream of event notifications,
• using the QUERY method ().

Since the content of the response is an event notification, a client can negotiate its form with header fields in the usual manner.

Single Event Notification Request

Response When a single notification is requested, the server MUST end the response immediately after sending the event notification.

Single Event Notification Response

​

Notifications Stream Events Query can also be used to request a stream of multiple event notifications ().

Request To receive multiple notifications, a client MUST:

• send a realization of the subscription data model that includes an interest in receiving a stream of event notifications in a preferred form,
• using the QUERY method ().

Since the response transmits event notifications within an encapsulating representation (), it follows that header fields cannot be used to negotiate the form of event notifications as in the case of Single Notification Request. Instead, header fields are useful for negotiating the representation that encapsulates event notifications. The following examples illustrate subscription requests that negotiate a stream of event notifications to be transferred respectively using a composite media type (multipart/mixed) and a discrete media type (application/json-seq): The first example shows a subscription request for effectively a stream of discrete Single Notifications to be transferred using multipart/mixed () as the encapsulating media type. The events property in this example indicates an interest in receiving event notifications and its sub-properties describe the preferred form of notifications. Since the notifications are transferred as a pipeline of HTTP messages, these sub-properties are identical to header fields used for specifying preconditions and content negotiation in a Single Notification Request.

Request for Multipart Notifications Stream

The second example shows a subscription request for a stream of JSON notifications to be transferred using application/json-seq () as the encapsulating media type. The events property in this example is being used to communicate the preferred schema for the requested event notifications.

Request for JSON Notifications Stream

Response The response stream transmits multiple event notifications in an encapsulating media type. The following illustrates event notifications streamed in both a composite media type (multipart/mixed) and a discrete media type (application/json-seq) in response to the example requests in .

Headers A server able to provide a stream of event notifications MUST immediately send headers, which include:

• The Events header field, to communicate the properties of the notifications stream.
  • The duration property, set to the maximum duration for which the server intends to serve event notifications.
• The Incremental header field () set to ?1 to indicate that the response is to be immediately forwarded by intermediaries and not buffered.

Notifications Stream Response Headers

The Content-Type header field in response to the request in the first example is:

Notifications Stream Multipart Content Response Header

whereas in response to the request in the second example is:

Notifications Stream JSON Content Response Headers

Notifications Subsequently, when event(s) occur, the server transmits a notification. An event notification transferred in a multipart/mixed response stream is identical to the Single Notification Response, except that non "Content-*" fields are excluded as required by :

Multipart Update Notification

The same event notification when transferred in an application/json-seq response stream is as follows:

JSON Update Notification

A server MUST end the response immediately after transmitting the event notification that signals the deletion of a resource. The notification for a delete event expressed inside a multipart message might be as follows:

Multipart Delete Notification

The same notification for a delete event as JSON would be as follows:

JSON Delete Notification

Otherwise, a server MUST end the response when the connection duration exceeds the period set in the duration property of the Events header field.

Representation Events Query enables a user agent to ask and receive the current representation and subsequent event notifications in a single request/response. When compared to using, say, Fetch and EventSource (, Section 9.2.2) in conjunction, Events Query not only saves on an extra round trip, but also relieves a user agent from the burden of synchronizing the representation with event notifications.

Request To receive a representation of the resource alongside notifications, a client MUST:

• send a realization of the subscription data model that includes an interest in receiving a stream containing:
  • the representation(s) in a preferred form, and
  • event notifications in a preferred form,
• using the QUERY method ().

The following example shows a subscription request for the current representation along with the subsequent event notifications transmitted using the multipart/mixed media type. The state property indicates interest in receiving representation and its sub-properties describe the preferred form of notifications. Since the representation is being transferred in an HTTP message pipeline, these sub-properties are identical to header fields used for specifying preconditions and content negotiation in a GET request on the said resource.

HTTP Representation and Notifications Request

Response A server unable to provide a representation MUST NOT serve event notifications. This does not apply to a conditional request for representation that is not fulfilled. A server able to provide a stream with a representation and event notifications transmits the representation immediately following the response headers (). Otherwise, the response is the same as that described in . Again, the multipart-mixed media type () is used for the purpose of illustration. Chunks have been omitted for clarity.

Representation Response before Notifications

While this is default behavior, there is no requirement that a representation is the first message or that representations are sent only once. In such cases, the encapsulated message needs to indicate if it is a representation and not an event notification. Such a mechanism is beyond the scope of this specification (see ). Notifications are transmitted just as in the case of regular streaming. See for a complete example of a response with representation and notifications.

Implementation Status

Express Demo A toy server built in Express.js demonstrating the Events Query Protocol is available at . This demo is powered by the following libraries:

• Negotiate Events Field: To read the request Events header field () and negotiate the response duration (),
• NOSE: To observe events on resources and generate notifications in a preferred format, and
• Extended Response: To write the representation and event notifications on the response stream for a given duration ().

The demonstration and libraries are Free and Open Source Software, released under the Mozilla Public License, v. 2.0. Please contact the author for more information about these programs.

CAMARA API Demo A second, independent implementation by Jaime Jiménez that applies Events Query in an agent-ready mock for the CAMARA (Global Telco API Alliance) HTTP APIs is available at . The CAMARA sandbox uses Events Query to notify clients of SIM-swaps. An agent can observe changes to the SIM-swap state in-band as a JSON Sequence by sending a QUERY request to a resource, rather than setting up a separate Webhooks subscription.

Security Considerations Events Query is subject to the security considerations of the HTTP QUERY method () and more generally HTTP Semantics. Considerations relevant to the use of HTTP QUERY method are discussed in . HTTP Semantics and its use for transferring information over the Internet are discussed in . When serving event notifications, servers are required to keep the response stream open for an extended period of time. Since the effort required to request notifications is tiny compared to the time, memory, and bandwidth consumed attempting to serve the notifications, servers implementing Events Query have increased susceptibility to Denial-of-Service attacks. Servers ought to ignore, coalesce, or reject egregious subscription requests, such as repeated requests from the same origin within a short interval of time. Resource authorization can change during the lifetime of a response. A server that enforces access control on a resource must ensure that it does not transmit notifications once the authorization carried by the request has expired or been revoked. If the authorization can be revoked mid-response, the server must check the validity of the authorization before each notification is sent and immediately end the response upon discovering that the authorization is invalid.

IANA Considerations The change controller for the following registrations is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".

HTTP Field Registration IANA is requested to add the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" (see ): List of HTTP Field Name registrations

Header Field Names	Status	Structured-Type	Reference
Events	Permanent	Dictionary

The HTTP Events Field Registry IANA is requested to create a new registry, "HTTP Events Field Registry", under the Hypertext Transfer Protocol (HTTP) Parameters registry to register properties for use in the Events header field. New registrations will use the Specification Required policy ().

Template The registration of an Events property MUST include the following fields:

• Property Name: A Dictionary () key to be used in the Events header field.
• Structured Type: The Structured Data Type () of the value associated with the key, according to requirements in .
• Reference: A pointer to the specification text.

The registration MAY also include the following fields:

• Optional Parameters: An enumeration of optional parameters and the Structured Data Type () of value associated with the parameter, according to requirements in
• Comments: Additional information to be included in the template.

Initial Registry Contents The initial contents of the HTTP Events Field Registry are: List of HTTP Events Field property name registrations

Property Name	Structured-Type	Reference
duration	Integer or Decimal Item

End User Considerations "The mission of the IETF is to produce high quality, relevant technical and engineering documents that influence the way people design, use, and manage the Internet in such a way as to make the Internet work better" . The mission statement further goes on to state, "We want the Internet to be useful for communities that share our commitment to openness and fairness. We embrace technical concepts such as decentralized control, edge-user empowerment and sharing of resources, because those concepts resonate with the core values of the IETF community." . The Internet Architecture Board says that the "Internet is for end users" and "argues that the IETF should favor their interests over those of other parties" . It logically follows that technical documents produced by the IETF ought to consider their impact on the Internet end user. For this reason, I suggest that specifications include a considerations section where authors assess the technical decisions and trade-offs in their proposals based on their ramifications on the interests of end users. End users of the HTTP protocol can be classified into two groups: publishers and consumers. Consumers have an incentive to subscribe to event notifications from many resources and to hold on to a connection for as long as possible; whereas publishers bear the cost of server infrastructure. Consumers also typically outnumber publishers, in many cases by multiple orders of magnitude. This creates an imbalance in the effort to subscribe versus effort to deliver; consumers can easily place a disproportionate burden on servers, reminiscent of a denial-of-service attack. At the outset, requiring that clients subscribe to event notifications per resource serves as an effective filtering mechanism that limits the burden on servers. Compare this to the typical implementation of protocols such as WebSockets , where clients connect to dedicated endpoints to receive notifications; the server either has to broadcast notifications for multiple resources or track resources of interest for each client to filter event notifications accordingly. Events Query empowers servers to decide, for any given resource, the events for which notifications are served and the content of the notifications. Servers are able to choose the duration for which they wish to serve notifications and are also free to end the response at any time. Servers implementing Events Query might, thus, be able to offer differentiated service to consumers. Authenticated consumers, for example, might be asked to share the cost burden with publishers in return for a higher quality of service. The use of HTTP Semantics also enables intermediation of event notifications, unlike existing mechanisms built with protocols such as WebSockets or WebSub . Intermediaries can help with improving the latency and reliability of transmission of event notifications as well as scaling of the event notification traffic to reach a significantly larger base of consumers. On the flip side, economies of scale will likely lead to greater consolidation of intermediary service providers (though not centralization) with the attendant risk of anti-consumer behavior. In the opinion of the authors, policies designed to treat network traffic as a public utility might provide better outcomes for the end user.

References Normative References 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. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. This specification defines the QUERY method for HTTP. A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing. This is similar to POST requests, but QUERY requests can be automatically repeated or restarted without concern for partial state changes. Fastly Apple Mozilla This document specifies the "Incremental" HTTP header field, which instructs HTTP intermediaries to forward the HTTP message incrementally. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. 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. Informative References Infrequently Noted Dept. of Info. & Computer Science, University of California, Irvine, Irvine, CA Dept. of Computer Science, University of Colorado, Boulder, CO Association for Computing Machinery (ACM) 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 obsoletes RFC 7234. University of California, Irvine Chapter 5, Architectural Styles and the Design of Network-based Software Architectures This second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK] This memo gives a mission statement for the IETF, tries to define the terms used in the statement sufficiently to make the mission statement understandable and useful, argues why the IETF needs a mission statement, and tries to capture some of the debate that led to this point. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. On today's Internet, the Hypertext Transfer Protocol (HTTP) is often used (some would say abused) to enable asynchronous, "server- initiated" communication from a server to a client as well as communication from a client to a server. This document describes known issues and best practices related to such "bidirectional HTTP" applications, focusing on the two most common mechanisms: HTTP long polling and HTTP streaming. This document is not an Internet Standards Track specification; it is published for informational purposes. This document describes the JavaScript Object Notation (JSON) text sequence format and associated media type "application/json-seq". A JSON text sequence consists of any number of JSON texts, all encoded in UTF-8, each prefixed by an ASCII Record Separator (0x1E), and each ending with an ASCII Line Feed character (0x0A). This document specifies "Alternative Services" for HTTP, which allow an origin's resources to be authoritatively available at a separate network location, possibly accessed with a different protocol configuration. This document explains why the IAB believes that, when there is a conflict between the interests of end users of the Internet and other parties, IETF decisions should favor end users. It also explores how the IETF can more effectively achieve this. Applications often use HTTP as a substrate to create HTTP-based APIs. This document specifies best practices for writing specifications that use HTTP to define new application protocols. It is written primarily to guide IETF efforts to define application protocols using HTTP for deployment on the Internet but might be applicable in other situations. This document obsoletes RFC 3205.

Examples Some examples used in this specification are consolidated below. Chunks have been omitted for clarity.

Representation and Notifications The following example illustrates a complete request and response for representation and notifications transferred with the multipart/mixed media-type as described in :

Request

Request for Representation and Notifications

Response

Response with Representation and Notifications

Notifications Stream The following example illustrates complete request and response for JSON formatted notifications transferred with the application/json-seq media-type as described in :

Request

Request for JSON Notifications

Response

Response with JSON Notifications

Acknowledgments We thank members of the HTTP Working Group, the HTTPAPI Working Group, the Solid community, the Braid community and others for discussions, ideas, reviews, and feedback on previous work that has led to this specification.