]>

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. 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 for transferring static documents within a single request and response. HTTP does not automatically inform clients of changes to a document. This design was adequate for web pages that were mostly static and written by hand. But web-applications today are dynamic, requiring instantaneous updates from sources. The many workarounds developed over the years to provide real-time updates for resources using HTTP have proven to be inadequate. Web programmers instead resort to implementing custom messaging systems over alternate protocols such as WebSockets , which requires additional layers of code, typically involving non-standard JavaScript frameworks to provide event notifications. It also requires additional work to coordinate a representation and notifications that are served on different protocols. Events Query is a minimal protocol built on top of 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. Programmers implementing Events Query shall no longer be forced to switch to another protocol to incorporate real-time functionality in their web applications. Not only that, web-applications shall receive a representation and notifications in a single response, obviating any need for co-ordination and saving on unnecessary roundtrips. 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 HTTP based 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 mechanisms like Conflict Free Replicated Data Types (CRDT) or Operational Transforms (OT), event notifications can be used create representations that are "live" for user agents. This has the potential to immensely simplify the task of programming multi-author distributed real-time applications.

Design Events Query is predicated on a resource being the most intuitive source for notifying its events. 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. Unlike other protocols, Events Query does not (usually) require additional resources to be specifically dedicated as endpoints for delivering event notifications. By giving a resource the ability to send notifications when an event occurs, Events Query aims to reduce the complexity of both servers and clients implementing notifications, making it easier to develop real-time applications.

Goals The goals of the Events Query are:

1. to use the Hypertext Transfer Protocol for reliable and in-order transfer of event notifications. Clients fetching resources using HTTP need not required to switch to another protocol for receiving event notifications.
2. to provide updates directly from a resource of interest, obviating the need to create another endpoint for event notifications. This eliminates the need to co-ordinate responses between a resource and the notification endpoint as is the case with existing approaches.
3. to allow clients to fetch representation and notifications in response to a single request, minimizing round-trips between clients and servers and eliminating the need to manage race conditions between responses.
4. to allow event notifications to be communicated in any arbitrary format that might be negotiated. Implementers shall be able to provide more expressive notifications in comparison to existing HTTP based messaging protocols such as Server Sent Events .
5. to specify transparent semantics that allow intermediaries to participate in scaling, improving reliability, and reducing latency of event notifications as well as proactively update caches.

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 HTTP resource to provide event notifications. Implementers shall be able to scale notifications along with their data/applications.

Scope The Events Query Protocol specifies:

1. A mechanism to discover notification capabilities 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 the subscription ().
4. Semantics for a response carrying a single notification.
5. Semantics for the response streaming multiple event notifications as well as the representation, if requested.

The Events Query Protocol does not specify:

1. A realization of the abstract data model used for requesting event notifications. For the purposes of illustration, we shall use an imaginary example/event-request media-type for the request.
2. Specific events for which a notification is generated. Events for which notifications are generated can vary per resource.
3. The form or content of an event notification. Implementations have the flexibility to generate event notifications for the applications they wish to support on a resource. We shall use a very simple YAML notification using an imaginary example/event-response media-type for illustration.
4. Specific representations for the response stream with multiple notifications. For the purpose of illustration, we shall use the application/http media-type () as the composite media-type for the response that includes a representation and/or multiple event notifications.

Limitations Events Query only allows notifications to be sent for events on a given resource. To send notifications for events on multiple resources in a single response, implementations will need to mint separate resources as notification endpoints. This is no different from APIs built on top of existing messaging protocols (See, for example, and ). 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 streaming based protocols, such as Server-Sent Events . 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 to maximize the number of concurrent connections and to provide 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 opening multiple simultaneous persistent connections to any given host.

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 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 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 of 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 The Events header field when used by a client in a request communicates preferences for the Events Query response. The Events header field is not meant for content negotiation. The Events header field allows a server to communicate the properties of a response carrying event notifications. Events is a Dictionary structured header field (). The order of keys is insignificant. Senders SHOULD NOT generate keys not registered with the HTTP Event Field Registry (An exception is made to allow for experimentation). Recipients MAY ignore keys that they are unaware of.

duration Property The duration property when be used by a client in a request specifies the duration for which they prefer the response stream to remain open. A server is completely free to ignore this property. The duration property when used by a server in a response indicates the minimum duration for which a server intends to keep the response stream open. This property is merely advisory, and a server might still close the response stream before this duration. The duration property is a key specified in the Events header field. It is of the type Integer () with its value indicating duration in seconds. Only positive integer values are valid. A value of 0 indicates an indefinite duration. 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 MUST allow a client to specify in a subscription request:

• interest in receiving a representation in a preferred form.
• interest in receiving event notifications in a preferred form.

Implementations can choose an appropriate media-type 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 outside the scope of this specification. 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 event query is to ask for a notification for the next event(s) on a resource. This, in effect, adds long-polling capability () to a resource.

Request To be notified of the next event(s) on a resource using Events Query, a client can send an empty query. A server MUST consider a request with an empty query in an appropriate media-type made using the QUERY method () as a subscription request for a single event notification. A client can, as usual, negotiate the form of the event notification using header fields.

Single Event Notification Request

Response When providing a single notification, the server MUST close the connection immediately after transmitting the event notification.

Single Event Notification Response

​

Notification Stream Instead of long-polling for event notifications, Events Query can also be used request a stream () of multiple event notifications.

Request To request a stream of event notifications from a resource in an Events Query, a client MUST express the interest in receiving the event notifications in a preferred form using a realization of the subscription data model with the QUERY method (). A client can also negotiate the response that encapsulates event notifications using header fields. Since the response carries an encapsulating representation, header fields can no longer be used to negotiate the form of an event notification itself like in the case of a Single Notification Request. The following example shows subscription request for a stream of event notifications transmitted using the application/http media-type. The events property indicates the interest in receiving event notifications. Preferences are specified using the request headers in the events property.

Notifications Stream Request

Response The response stream encapsulates multiple event notifications (typically, but not necessarily) in a composite media-type. We shall be using application/http media-type () for the purpose of illustration.

Headers A server able to provide a stream of event notifications immediately sends the header which MUST include:

• The Events header field to communicate the properties of the notifications stream.
  • The duration property set with the time for which the server intends to serve 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

Notifications Subsequently, when event(s) occur, the server transmits a notification identical to the Single Notification Response, except header fields redundant with response header () are omitted.

Update Notification

A server MUST end the response immediately after transmitting the event notification upon a resource being deleted.

Delete Notification

Otherwise, a server MUST end the response when the connection duration has exceeded the period set in the duration property of the Events header field. A server MAY terminate the response earlier.

Representation Events Query lets 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 in conjunction, Events Query not only saves on an extra round trip, but relieves a user agent from the burden of handling the possible race condition.

Request To request a representation of the resource in an Events Query, a client MUST express the interest in receiving the representation in a preferred form using a realization of the subscription data model () with the QUERY method (). The following example shows subscription request for representation along with notifications transmitted using the application/http media-type. The state property indicates the interest in receiving representation. The preferred form of representation is specified using the request headers in the state property.

Representation and Notifications Request

Response A server unable to provide a representation MUST NOT serve event notifications. This does not apply in case of 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 header (). Otherwise, the response is the same as that described in . Again, we shall use the application/http media-type () for the purpose of illustration. Chunks have been omitted for clarity.

Representation Response

While this is default behaviour, there is no requirement that a representation is the first message or is 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 not defined in this specification. Notifications are transmitted just as described in . See for a complete example of a response with representation and notifications.

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 and HTTP Semantics and its use for transferring information over the Internet are discussed in . When serving a stream of event notifications, resources are required to keep the response stream open for an extended period of time, making them more susceptible to Denial-of-Service attacks because the effort required to request notifications from the same resource is tiny compared to the time, memory, and bandwidth consumed by attempting to serve the notifications. Servers ought to ignore, coalesce, or reject egregious event notification request, such as repeated notification requests to a resource from the same origin.

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 Item

End User Considerations If we, the IETF, claim that the Internet is for the end user and promote the end-to-end principle , every specification we produce ought to consider its impact on the Internet end user. For this reason, I propose that specifications must include a considerations section where authors assess the impact of their proposal on the internet end user, aligned with the mission of IETF . 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 content and duration for which event notifications are served on any given resource, as well as allowing servers to close the response stream at any time. Servers may also limit event notifications and/or their content, except to authenticated consumers. Such authenticated consumers might, for example, 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 behaviour. 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. greenbytes GmbH Akamai This specification defines a new HTTP method, QUERY, as a safe, idempotent request method that can carry request content. 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 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 Internet Architecture Board The end-to-end principle is the core architectural guideline of the Internet. In this document, we briefly examine the development of the end-to-end principle as it has been applied to the Internet architecture over the years. We discuss current trends in the evolution of the Internet architecture in relation to the end-to-end principle, and try to draw some conclusion about the evolution of the end-to-end principle, and thus for the Internet architecture which it supports, in light of these current trends. This memo provides information for the Internet community. 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 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. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document specifies the HTTP/1.1 message syntax, message parsing, connection management, and related security concerns. This document obsoletes portions of RFC 7230. 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.

Example The following example illustrates a complete request and response for representation and notifications using Events Query. Chunks have been omitted for clarity.

Request

Request for Representation and Notifications

Response

Response Stream with Representation and Notifications

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