draft-toomim-httpbis-versions-05.txt

Internet-Draft                                                 M. Toomim
Expires: Aug 20, 2026                                  Invisible College
Intended status: Proposed Standard                          Mar 02, 2026


                        HTTP Resource Versioning
                    draft-toomim-httpbis-versions-05

Abstract

   HTTP resources change over time.  Each change to a resource creates a
   new "version" of its state.  HTTP systems often need a way to
   identify, read, write, navigate, and/or merge these versions, in
   order to implement cache consistency, create history archives, settle
   race conditions, request incremental updates to resources, interpret
   incremental updates to versions, or implement distributed
   collaborative editing algorithms.

   This document analyzes existing methods of versioning in HTTP,
   highlights limitations, and specifies a more general versioning
   approach that can enable new use-cases for HTTP.  An upgrade path for
   legacy intermediaries is provided.


Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as
   Internet-Drafts.  The list of current Internet-Drafts is at
   https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   https://www.ietf.org/1id-abstracts.html

   The list of Internet-Draft Shadow Directories can be accessed at
   https://www.ietf.org/shadow.html


Table of Contents

   1.  Introduction .................................................4
   2.  HTTP Resource Versioning .....................................5
   2.1.  Model of time ..............................................5
   2.2.  Version and Parents headers ................................6
   2.2.1.  Formatting of Version IDs in versioning headers ..........7
   2.2.2.  Definition of Events and Versions ........................7
   2.3.  Using Versioning with HTTP Methods .........................8
   2.3.1.  GET the current version ..................................8
   2.3.2.  GET a specific version ...................................9
   2.3.3.  PUT, POST, or PATCH a new version ........................9
   2.3.4.  GET a range of historical versions ......................10
   2.3.5.  Rules for Version and Parents headers ...................12
   2.3.6.  Interaction with Conditional Request Headers ............12
   2.5.  Status 432: Version Not Found .............................13
   2.6.  The Current-Version header ................................13
   2.7.  Version-Type header .......................................14
   2.8.  Versioning through intermediaries .........................15
   2.8.1.  Detecting legacy intermediaries .........................16
   3.  Analysis of existing versioning approaches in HTTP ..........17
   3.1.  Approaches with versions in headers .......................17
   3.1.1.  Last-Modified ...........................................17
   3.1.2.  ETag ....................................................18
   3.2.  Approaches defining versions as new resources .............19
   3.2.1.  Creating additional "Version Resources" .................19
   3.2.2.  Standardizing versions as external resources ............20
   3.4.  Requirements for general versioning .......................21
   3.4.1.  Distributed Time ........................................21
   3.4.2.  Included within existing HTTP requests and responses ....22
   3.4.3.  Generalizable Timestamps ................................22
   3.5.  Feature table of existing approaches ......................23
   4.  Informative Use-Cases .......................................24
   4.1.  Incremental RSS Subscription ..............................24
   4.2.  Hosting git via HTTP ......................................25
   4.3.  Resumable uploads protocol ................................28
   4.4.  Distributed collaborative editing .........................30
   4.5.  Improved Header Compression with runs .....................32
   4.6.  Run-Length Compression without Header Compression .........35
   5.  Acknowledgements ............................................36
   6.  Conventions .................................................36
   7.  IANA Considerations .........................................37
   7.1.  HTTP Header Registrations .................................37
   7.2.  Version Type Registry .....................................37
   7.2.1.  Procedure ...............................................38
   7.2.2.  Version Type Registrations ..............................39
   7.2.2.1.  The peer-counter Version-Type .........................39
   7.2.2.1.1.  The "text-runs" modifier ............................39
   7.2.2.1.2.  The "bytestream" modifier ...........................39
   7.2.3.  Comments on Version Type Registrations ..................40
   7.2.4.  Change Procedures .......................................40
   8.  Copyright Notice ............................................41
   9.  Security Considerations .....................................42
   10.  Authors' Addresses .........................................43
   11.  References .................................................43
   11.1.  Normative References .....................................43
   11.2.  Informative References ...................................43


1.  Introduction

   HTTP resources change over time.  Any single computer on the network
   can observe a resource changing, over time, in a linear sequence of
   versions:


                  o  <-- oldest version
                  |
                  o
                  |
                  o
                  |
                  o  <-- newest version


   We call this a "linear" history.

   However, when multiple networked computers change a resource
   "simultaneously" -- before their edits propagate to one another --
   the global perspective of version history actually forks into a DAG,
   or "partial order":


                  o  <-- oldest version
                 / \
                o   o
                 \ /
                  o
                  |
                  o  <-- newest version


   HTTP systems often need to specify, identify, and navigate these
   histories of versions in order to (1) implement cache consistency,
   (2) create history archives, (3) settle race conditions, (4) request
   incremental updates to resources, (5) interpret incremental updates
   to versions, or (6) merge parallel mutations in distributed
   collaborative editing algorithms.  Section 4 demonstrates these
   use-cases concretely.

   Each of these systems needs a way to represent *time*, but different
   systems have different requirements for how time is represented.
   This document enumerates these needs, and proposes a general
   versioning system to satisfy them.

   (Note that this document does NOT speak to the versioning of HTTP
   APIs -- only HTTP resources, which are used within APIs.)


2.  HTTP Resource Versioning

   This section defines the core concepts and mechanisms for HTTP
   Resource Versioning.


2.1.  Model of time

   This specification adds a dimension of time to HTTP resources.
   Whereas HTTP Resources already have a dimension of *space* -- queried
   with the Range header -- this specification provides Resources a
   dimension of *time* -- queried by the Version header:


            == Time and Space as dimensions of Resources ==

        Resource Representation      <-- URI + Content-Type: header

        ^
        |
        |
        |         Time               <-- Version: header
        |       /
        |     /
        |   /
        | /
        +----------------> Space     <-- Range: header


   Any Resource can thus be queried for its Time and Space, via a
   Version and Range:


           GET /foo
           Version: "v1.2.3"
           Range: bytes 500-1000


   In this model, the term "Version" is synonymous with "Timestamp" -- a
   Version represents a point in distributed time.  Thus, a Version, on
   its own, identifies a version of the Universe of Resources -- the
   version that existed at that time.  We can use a Version to identify
   a point of time for a single Resource, or for multiple Resources, to
   identify their states at the same version in time.  A Version can be
   specified without reference to a particular resource.

   It follows that a "Version of a Resource" specifies the state of the
   Resource at the time of that Version.  The "Version of a
   Representation" further implies a particular state of the
   Representation body, or "snapshot."

   Note that this model differs in terminology from some other
   mechanisms, such as WebDAV Versioning, which use the term Version for
   what we call a "Version of a Representation."

   A resource's "Version History" is the partial order (or DAG) of
   Versions of its state.  This history has one fork and one merge:


                     "1"                   | Time
                     / \                   |
                   "2" "3"                 |
                     \ /                   |
                   "2","3"  <-- merge      |
                      |                    |
                     "4"                   V


   The semantics of a merge is specified by the resource's Merge-Type.
   (See [Merge-Types].)


2.2.  Version and Parents headers

   This specification introduces two new HTTP headers: Version and
   Parents.  These headers communicate version information in requests
   and responses.

   The Version header specifies the current version of a resource:

           Version: "dkn7ov2vwg"

   The Parents header specifies the immediate predecessor version(s):

           Parents: "ajtva12kid", "cmdpvkpll2"

   These headers may be used in PUT, PATCH, POST, and DELETE requests,
   and GET and HEAD responses, to convey the version before and after
   the Update conveyed by the HTTP message.  (See [Updates].)

   These headers can also be used in GET and HEAD requests to ask a
   server for a specific version or range of version history.

   If an Update (a PUT, PATCH, POST, or DELETE request, or a GET or HEAD
   response) does not specify a Version header, the recipient MAY
   generate and assign it a new version ID.  If an Update does not
   specify a Parents header, the recipient MAY presume that the most
   recent versions it has (the frontier of time) are the parents of the
   new version.

   To describe a merger, a Version header MAY contain multiple IDs:

           Version: "dkn7ov2vwg", "v2vwgdkn7o"


2.2.1.  Formatting of Version IDs in versioning headers

   The Version and Parents headers are formatted as a list of strings
   and/or display strings in the Structured Headers format [RFC9651].
   Each string is called an Event ID.

           Version:           <version>
           Parents:           <version>

           <version>:         <event-id>, <event-id>, ...
           <event-id>:        <string> | <display-string>

   The ordering of IDs within a Version or Parents header carries no
   meaning.  Event IDs SHOULD be sorted lexicographically whenever
   received or sent, with exactly one space after "," separators, to
   canonicalize the set's serialization as a unique string, e.g. as a
   unique cache key.

   The formatting of Event IDs is constrained according to the
   resource's Version-Type, as defined in Section 4.

   Note that structured header strings "..." can only contain printable
   ASCII.  If an Event ID contains unicode beyond printable ASCII, it
   should be formatted as a display string %"..." instead.


2.2.2.  Definition of Events and Versions

   An "Event" is a unique ID assigned to a single event in history at a
   peer.  Any peer can define an event, by generating a unique ID.
   Events are generally defined at state mutations, but events MAY also
   be defined at a "no-op mutation", when a unique identifier to mark
   time is desired.

   Conceptually, for any event E, all prior events that have been
   observed by that peer before defining E can be referenced as the set
   ancestors(E).  The frontier of this set, or frontier(ancestors(E)),
   is defined as the events that are not in the ancestors(e') for any
   other event e' in ancestors(E).  We define the parents(E) to be this
   frontier(ancestors(E)).

   A Version in time is likewise defined by the set of observed events
   at that time, and we define any Version V as the
   frontier(observed_events) at that time.

   Thus, the version immediately after any event E is simply the set
   {E}, and the version after the merger of two parallel events E1 and
   E2 is the set {E1, E2}.

   As a result, the version of a resource immediately after a mutation
   will contain just a single string:

           Version: "foo-123"

   The version of a merger will generally contain multiple strings:

           Version: "foo-123", "bar-abc"

   However, it is also possible for a peer to define a no-op event that
   represents the merger as a single string:

           Parents: "foo-123", "bar-abc"
           Version: "{foo-123, bar-abc}"


2.3.  Using Versioning with HTTP Methods

   The Version and Parents headers can be set in requests and
   responses of methods:

     - GET
     - HEAD
     - PUT
     - PATCH
     - POST

   For each of these methods, if a Version or Parents header exists in
   the request, it should also exist in the response, and if not, the
   server may nonetheless specify it in its response.

   We now detail the ways in which these headers modify requests and
   responses for these methods.


2.3.1.  GET the current version

   If the Version: header is not specified, a GET request returns the
   current version of the state as usual:

      Request:

         GET /chat

      Response:

         HTTP/1.1 200 OK
         Version: "ej4lhb9z78"
         Parents: "oakwn5b8qh", "uc9zwhw7mf"
         Content-Type: application/json
         Content-Length: 64

         [{"text": "Hi, everyone!",
           "author": {"link": "/user/tommy"}}]


   The server MAY include a Version and/or Parents header in the
   response, to indicate the current version and its parents.

   Clients can use a HEAD request to elicit versioning history without
   downloading the body:


      Request:

         HEAD /chat

      Response:

         HTTP/1.1 200 OK
         Version: "ej4lhb9z78"
         Parents: "oakwn5b8qh", "uc9zwhw7mf"
         Content-Type: application/json


2.3.2.  GET a specific version

   A server can allow clients to request historical versions of a
   resource in GET requests by responding to the Version and Parents
   headers.  A client can specify a specific version that it wants with
   the Version header:


      Request:

         GET /chat
         Version: "ej4lhb9z78"

      Response:

         HTTP/1.1 200 OK
         Version: "ej4lhb9z78"
         Parents: "oakwn5b8qh", "uc9zwhw7mf"
         Content-Type: application/json
         Content-Length: 64

         [{"text": "Hi, everyone!",
           "author": {"link": "/user/tommy"}}]


2.3.3.  PUT, POST, or PATCH a new version

   When a PUT, POST, or PATCH request changes the state of a
   resource, it can specify the new version of the resource, and the
   parent version that it was based on:


      Request:

         PUT /chat
         Version: "ej4lhb9z78"
         Parents: "oakwn5b8qh", "uc9zwhw7mf"
         Content-Type: application/json
         Content-Length: 64

         [{"text": "Hi, everyone!",
           "author": {"link": "/user/tommy"}}]
                  

      Response:

         HTTP/1.1 200 OK


   The Version and Parents headers are optional.  If Version is omitted,
   the recipient may assign new event IDs.  If Parents is omitted, the
   recipient may assume that its current version is the version's
   parents.


2.3.4.  GET a range of historical versions

   A client can request a range of history by including a Parents and a
   Version header together.  The Parents marks the beginning of the
   range (the oldest versions) and the Version marks the end of the
   range (the newest versions) that it requests.


      Request:

         GET /chat
         Version: "3"
         Parents: "1a", "1b"

      Response:

         HTTP/1.1 209 Multiresponse
         Current-Version: "3"

         HTTP/1.1 200 OK
         Version: "2"
         Parents: "1a", "1b"
         Content-Type: application/json
         Content-Length: 64

         [{"text": "Hi, everyone!",
           "author": {"link": "/user/tommy"}}]

         HTTP/1.1 200 OK
         Version: "3"
         Parents: "2"
         Content-Type: application/json
         Merge-Type: sync9
         Content-Length: 117

         [{"text": "Hi, everyone!",
           "author": {"link": "/user/tommy"}}
          {"text": "Yo!",
           "author": {"link": "/user/yobot"}]
   

   Note that this example uses a new "Multiresponse" code, which is
   currently being drafted [Multiresponse].  See [Braid-HTTP] Section 3
   for an earlier draft of the semantics.

   If the client just wants the version identifiers for a range of
   history, it can use a HEAD request:


      Request:

         HEAD /chat
         Parents: "ej4lhb9z78"
         Version: "oakwn5b8qh"

      Response:

         HTTP/1.1 209 Multiresponse

         HTTP/1.1 200 OK
         Parents: "ej4lhb9z78"
         Version: "i8qa3vu1s0k"

         HTTP/1.1 200 OK
         Parents: "i8qa3vu1s0k"
         Version: "v1voi252yr"

         HTTP/1.1 200 OK
         Parents: "i8qa3vu1s0k"
         Version: "jn4zuwo0wum"

         ...


2.3.5.  Rules for Version and Parents headers

   If a GET request contains a Version header:

     - If the Parents header is absent, the server SHOULD return a
       single response, containing the requested version of the resource
       in its body, with the Version response header set to the same
       version.

     - If the server does not support historical versions, it MAY ignore
       the Version header and respond as usual, but MUST NOT include the
       Version header in its response.

   If a GET request contains a Parents header:

     - The server SHOULD send the set of versions updating the Parents
       to the specified Version.  If no Version is specified, then it
       should update the client to the server's current version.

     - If the server does not support historical versions, then it MAY
       ignore the Parents header, but MUST NOT include the Parents
       header in its response.

   A server does not need to honor historical version requests for all
   documents, for all history. If a server no longer has the historical
   context needed to honor a request, it responds with error code 432
   Version Not Found.


2.3.6.  Interaction with Conditional Request Headers

   The Version and Parents headers operate independently of the
   conditional request headers (If-Match, If-None-Match,
   If-Modified-Since, If-Unmodified-Since) defined in [RFC9110] Section
   13.  Conditional headers evaluate against entity-tags (ETags) or
   modification dates, while Version and Parents reference version
   identifiers.

   When both are present, the server SHOULD first resolve the requested
   version, then evaluate any preconditions.

   The Parents header in mutation requests (PUT, PATCH, POST) serves a
   related but distinct purpose from If-Match: whereas If-Match causes
   the request to fail if the resource's current state does not match,
   Parents specifies the version lineage of the mutation, which the
   server may use to detect conflicts, perform merges, or construct
   version history.


2.5.  Status 432: Version Not Found

   If a server does not have a version required of a request, it should
   respond with status 432 Version Not Found, and include copies of the
   request header(s) with versions it could not satisfy.  For example,
   if a client does:

           GET /foo
           Version: "alice-44"
           Parents: "bob-32"

   ...but the server does not have the versions 'alice-44', it should
   respond with:

           432 Version Not Found
           Version: "alice-44"

   Peers can drop history at any time.  Clients cannot rely on any
   particular portion of history existing on a server or intermediary
   when it makes requests.


2.6.  The Current-Version header

   While sending historical versions, a server or client can specify its
   current latest version with the Current-Version header.  The other
   party may desire this information to know when it has caught up with
   the latest version.  This is also used in the resumable uploads
   example below.


2.7.  Version-Type header

   The optional Version-Type header specifies constraints on the format
   and interpretation of event IDs.  This allows for various
   optimizations and specialized versioning schemes.

   For example:

           Version-Type: git

   This could indicate that event IDs will be git-style hashes,
   branches, or tags.  Peers could verify that the entire repository at
   a given version hashes to the specified ID.

   Another example:

           Version-Type: peer-counter; text-runs

   Diamond-Types, Automerge, and other algorithms use this format to
   compress history metadata through run-length encoding of consecutive
   insertions.  This allows a set of 50 inserted characters to be stored
   as 50 bytes plus one event ID, rather than 50 bytes plus 50 event
   IDs (each of which takes up multiple bytes).

   Implementers may define custom Version-Types to suit specific needs:

           Version-Type: version-vector

   A Version Vector Version ID might take the form:

           Version: "{peerid1: counter1, peerid2: counter2, ...}"

   Version Vectors enable direct computation of partial order between
   any two event IDs without examining the full version history graph.

   (To know the order between two Version Vectors A and B, one needs
   only to compare each peer's counter between A and B.  If A dominates
   across all peers, it is newer.  If B dominates, then it is newer.
   Otherwise, the ordering between the two version vectors is not known,
   and we can say that they happened in parallel.)


2.8.  Versioning through intermediaries

   Intermediaries can take advantage of versioning to uniquely
   reference, store, and serve multiple states/updates across a
   resource's history.  To distinguish versions, intermediaries must add
   the "Version" and "Parents" headers to their cache keys -- equivalent
   to the Vary header:

      Vary: version, parents

   Intermediaries SHOULD behave as if the Version and Parents headers
   have been added to the Vary header in every response passing through
   them.  To support legacy versioning-unaware intermediaries, the
   origin server is RECOMMENDED to explicitly add or extend Vary with
   "version, parents" in all its responses, unless it is certain that no
   legacy intermediaries will process the response.


2.8.1.  Detecting legacy intermediaries

   In the case that a legacy intermediary *does* process a versioned
   response without the Vary header, it can be detected by the client
   noticing that the Version and Parents Event IDs in a client request
   are not present in the request's response.  Here is an example:


      Presume we start with two versions:

         PUT /foo
         Version: "1"

         Hello

         PUT /foo
         Version: "2"

         Hello World!

      Now, if someone GETs the old version:

         GET /foo
         Version: "1"

      Then a versioning-aware origin server can return it:

         HTTP/1.1 200 OK
         Version: "1"

         Hello

      However, a versioning-unaware intermediary will cache this old
      response as if it is the current state.

      This breaks when a client requests the *newest* version:

         GET /foo
         Version: "2"

      And the cache ignores the Version header and returns what it has
      most recently seen:

         HTTP/1.1 200 OK
         Version: "1"

         Hello


   To detect this, the client SHOULD check that the Version and Parents
   headers in the response contain a superset of the Event IDs specified
   in the request.  (A missing Version or Parents header is considered
   to be an empty set for the version or parents of this superset
   calculation.)  The client can throw a warning to the programmer when
   encountering a response that does not contain the request's Event
   IDs, so that he knows to add Vary to the server's responses.


3.  Analysis of existing versioning approaches in HTTP

   Existing approaches to versioning in HTTP address disparate
   use-cases, but have limitations and trade-offs.  The Last-Modified
   and ETag headers were invented for cache consistency, but do not
   provide an ordering of version history through time, nor do they
   handle forks and merges in distributed time.  On the other hand, a
   number of forking/merging versioning systems have been proposed
   (WebDAV, Link Relations) that define new resources to represent
   versions of existing resources, but these require additional network
   round-trips to query and learn about these new version resources.  No
   HTTP versioning system today allows for articulating custom
   distributed timestamp formats such as version vectors.

   We now enumerate the existing approaches.  The following section
   provides an overview of their limitations for a general versioning
   system.


3.1.  Approaches with versions in headers

   The "Last-Modified" and "ETag" headers are by far the most
   commonly-used versioning system used in HTTP today.  They specify a
   resource's version directly in request and/or response headers.  This
   is simple and efficent, as versions are communicated immediately,
   without extra round trips, and very practically useful for caching
   and conditional requests.  However, the version format of
   Last-Modified and ETag do not provide enough information to compute
   an accurate order of versions, and thus cannot be used to represent
   distributed time.


3.1.1.  Last-Modified

   The Last-Modified header specifies a wallclock timestamp that caches
   and clients can use to know when a change has occurred:

      Last-Modified: Sat, 6 Jul 2024 07:28:00 GMT

   This header is useful for caching and conditional requests (using the
   If-Modified-Since header). However, it has several limitations:

   1. It is limited to the precision of the wallclock.  If a resource
      changes within the same second, the Last-Modified date won't
      change, and caches can become inconsistent.

   2. It stores linear time; not distributed (partial order) time.  It
      cannot represent the ambiguity of forked time.

   3. It is susceptible to clock skew in distributed systems,
      potentially leading to inconsistencies across different servers.


3.1.2.  ETag

   The ETag header allows more precision. It specifies a version with a
   string that uniquely identifies a cacheable representation:

           ETag: "2u34fa7yorz0"

   ETags can be strong or weak, with weak ETags prefixed by W/:

           ETag: W/"2u34fa7yorz0"

   ETags are used in conditional requests with If-None-Match and
   If-Match headers and can be used for optimistic concurrency
   control. However:

   1. While helping with cache validation, ETags are not accurate
      markers of time.  There is no way to order versions by ETag, or
      know which version came before another.
   
   2. ETags are unique to content, not timestamps.  It's possible for
      the same ETag to recur over time if the resource changes back and
      forth between a common state.

   3. Strong ETags are sensitive to Content-Encoding. If a single
      version of a resource is transmitted with different
      Content-Encodings (e.g., gzip), it will be sent with different
      strong ETags.

   Thus, one can have multiple ETags for the same version in history, as
   well as a single ETag for multiple versions of history.


3.2.  Approaches defining versions as new resources

   Rather than placing versioning information into headers, a second set
   of approaches create new "version resources" for each version of an
   original resource, and then add ways to navigate the "version
   resources."

   A variety of approaches exist -- from hand-copied "foo-v2.html" URIs,
   to standards like WebDAV.  However, they all require additional
   round-trips, with new URIs or new methods, to discover and navigate
   version information, which reduces performance, adds complexity, and
   makes it challenging for intermediaries to use versioning information
   without performing additional network requests themselves.


3.2.1.  Creating additional "Version Resources"

   Application programmers often define copies of a resource, at various
   versions, by encoding a version identifier into its URI:

      https://unpkg.com/braid-text@0.0.18/index.js

   This approach is common, but has several limitations:

   1. It loses the semantics of a "resource changing over time."
      Instead, it creates multiple version resources for each resource.

   2. It then necessitates standards to, given a URI, extract the
      current version of the resource, get the previous and next
      version(s), understand the format of the version(s) (e.g.,
      major.minor.patch), and to create new versions.  These standards
      are discussed next.

   3. It can lead to URI proliferation, complicating a web application's
      URI space, and potentially impacting caching strategies and SEO.


3.2.2.  Standardizing versions as external resources

   A number of approaches enable ways to organize and navigate a set of
   "version resources."  Memento [RFC7089] provides read-only access to
   prior states through datetime negotiation, but defines no mechanism
   for creating new versions.  WebDAV Versioning [RFC3253] provides a
   full lifecycle through CHECKOUT/CHECKIN methods, but requires
   server-assigned version identifiers.  Link Relations for Version
   Navigation [RFC5829] defines link relation types for navigating
   between version resources, but leaves the creation and management of
   those versions to other protocols.  WebDAV and Link Relations also
   allow for a partial order of distributed time, whereas Memento is
   limited to linear wallclock time.

   However, these approaches all require dereferencing additional URIs
   (and thus additional network round-trips) to discover version
   information, rather than embedding it inline in the headers of a
   normal GET or PUT to the resource.  This prevents intermediaries from
   organizing the version history without doing additional network
   requests themselves.  Furthermore, although WebDAV supports forking
   and merging history, the methods it provides to manipulate the
   history (CHECKIN, CHECKOUT, VERSION-CONTROL, LOCK, UNLOCK) require a
   centralized server.


3.4.  Requirements for general versioning

   This section defines the requirements for a general versioning
   standard.  It then provides a feature table enumerating which
   requirements the existing approaches support and do not support.

   These requirements are derived from the use-cases described in
   Section 4, which together span the range of versioning needs we have
   identified in HTTP systems -- from cache consistency and incremental
   updates, to distributed collaborative editing and hosting
   version-control systems like git.


3.4.1.  Distributed Time

   Distributed systems (see examples in section 4) require support for
   distributed time, including:

     (a) A comparable partial order:

         Any two Versions (timestamps) A and B must be comparable, such
         that either:

           - A > B:  A came after B
           - A < B:  A came before B
           - A <> B: Neither A nor B came before the other

     (b) Immune to clock skew or limited precision:

         The ordering must not depend on the skew or precision of a
         CPU's wallclock.

     (c) Merges must be specifiable without central authority:

         Any peer must be able to identify the version resulting from
         the merger of two parallel versions A and B, without relying on
         a central authority to assign a new version identifier AB.


3.4.2.  Included within existing HTTP requests and responses

   The versions should be included within existing HTTP requests and
   responses, wherever possible, without requiring additional requests
   and round-trips.  This simplifies implementation, improves
   performance, and allows intermediaries to understand and accurately
   cache the version history of state as it flows over the wire, without
   having to make additional requests themselves.  It also allows
   applications to add versioning information to their existing
   resources without impacting the definition of their existing URI
   space -- an unnecessary burden for many applications.

   We enumerate these requirements as follows:

      (a) Includes versioning in every existing request and response
          where state is queried or mutated.

      (b) Does not require additional round-trips.

      (c) Does not require polluting the application's URL namespace.


3.4.3.  Generalizable Timestamps

   Some systems have requirements for Version timestamps themselves:

      (a) Extensible timestamp formats:

          Advanced distributed systems often devise special formats for
          partially-ordered timestamps that allow inferences for
          improved performance, such as lamport clocks, vector clocks,
          version vectors, hash histories, hybrid logical clocks, and
          append-only-log indices.  Implementations can rely on
          information embedded in these timestamps to compress history
          metadata, optimize partial-order computations, or infer the
          value of state.

      (b) Independent of resource:

          Some applications need to assign a single version to multiple
          resources, so that one can refer to multiple resources at the
          same point in time.  For instance, a git repository (see
          section 4.2) commits multiple files at the same version.

          A general versioning system must provide version identifiers
          that are independent of any particular resource, so that
          multiple resources can be versioned and referred to at the
          same points in time.


3.5.  Feature table of existing approaches

   We compose a table of existing approaches, and the features they do
   not yet provide, here:


                         | 1a | 1b | 1c | 2a | 2b | 2c | 3a | 3b |
      ------------------------------------------------------------
      Last-Modified      | -  | -  | -  | X  | X  | X  | -  | X  |
      ETags              | -  | -  | -  | X  | X  | X  | -  | -  |
      Memento            | -  | ~  | -  | -  | -  | ~  | -  | -  |
      WebDAV Versioning  | X  | X  | -  | -  | -  | -  | -  | -  |
      Link Relations     | X  | X  | -  | X  | -  | ~  | -  | -  |
      ------------------------------------------------------------


   Because no existing versioning approach satisfies all needs,
   programmers today must implement multiple approaches to versioning in
   their applications -- each with subtly different logic -- and cannot
   implement common infrastructure for distributed versioning,
   archiving, and collaborative editing that works across HTTP systems.

   This document specifies a general versioning model satisfying all 8
   requirements above.  We start by specifying how to add versioning to
   HTTP requests and responses.


4.  Informative Use-Cases

   A general mechanism for versioning HTTP resources could enable a
   number of new use-cases:

     - RSS clients could request incremental updates when polling,
       instead of re-downloading redundant unchanged feed items after
       each change to any item

     - Servers could accept incoming patches based on old or parallel
       versions of history, and even rebase those patches for other
       clients, at other points in history

     - Collaborative editing could be built directly into HTTP
       resources, providing the abilities of Google Docs at any URL

     - Git repositories could be hosted directly over HTTP; rather than
       embedding versioning information within opaque blobs that use
       HTTP just as a transport

     - Caches and archives could hold and serve multiple versions of a
       resource, enabling audits and distributed backups

     - Distributed databases could standardize network APIs to HTTP,
       while retaining distributed consistency guarantees

   This section shows how to support some of these use-cases.


4.1.  Incremental RSS Subscription

   Traditional RSS readers inefficiently poll servers, often downloading
   entire feeds when only minor changes have occurred.  HTTP Resource
   Versioning enables more efficient incremental updates.

   A client can specify its last known version using the Parents header:


      Request:

         GET /feed.rss
         Accept: application/rss+xml
         Parents: "4"


   The server can then respond with only the changes since that version:


      Response:

         HTTP/1.1 200 OK
         Content-Type: application/rss+xml+patch
         Version: "5"
         Parents: "4"

         <?xml version="1.0" encoding="UTF-8" ?>
         <rss version="2.0">
         <channel>
          <title>My RSS Feed</title>
          <item>
           <title>This is a new entry</title>
           <description>Incremental update example</description>
           <link>http://www.example.com/blog/post/1</link>
          </item>
         </channel>
         </rss>


   This approach significantly reduces bandwidth usage and processing
   time for both client and server.  The specific patch format used can
   vary; see [Updates] or [Range-Patch] for examples.
   

4.2.  Hosting git via HTTP

   We can host a git repository directly through HTTP, where each file
   corresponds to a resource, and all have a version history.

   Git versions are normally specified as a hash.  The server can
   express this with a "Version-Type: git" header:

   
      Request:

         GET /repo/readme.md

      Response:

         HTTP/1.1 200 OK
         Content-Type: text/markdown
         Version-Type: git
         Version: "9531a9702af0d90dd489050ed8e25f87912a9252"
         Parents: "3a4c361f8e0349fe4b25c1ff46ebec1cec66e60f"

         ...


   Git also allows specifying a version with a short string, like
   "HEAD", which works for any tag or branch.  We can request the latest
   "development" branch version with:


      Request:

         GET /repo/readme.md
         Version: "development"

      Response:

         HTTP/1.1 200 OK
         Content-Type: text/markdown
         Version-Type: git
         Version: "9e26e8837a4f6a4445e74eed744fe8af85efd0c2"
         Parents: "1d5f89f8843b33b91d62bf95877e46b23fd86741"

         ...


   One can also request the files from release tagged "1.3.5" using:


      Request:

         GET /repo/readme.md
         Version: "1.3.5"


   One can clone a repo by asking for all versions from the root to
   HEAD:


      Request:

         GET /repo/readme.md
         Version: "HEAD"
         Parents: "ROOT"

      Response:

         HTTP/1.1 209 Multiresponse

         HTTP/1.1 200 OK
         Content-Type: text/markdown
         Version-Type: git
         Version: "9e26e8837a4f6a4445e74eed744fe8af85efd0c2"
         Parents: "1d5f89f8843b33b91d62bf95877e46b23fd86741"
         Content-Length: 190

         ...

         HTTP/1.1 200 OK
         Content-Type: text/markdown
         Version-Type: git
         Version: "1d5f89f8843b33b91d62bf95877e46b23fd86741"
         Parents: "1cf6ab4ed836d4d7308ac93edbc6fd18a69ef88f"
         Content-Length: 192

         ...


   In fact, git itself already supports two HTTP protocols: a "dumb" and
   a "smart" protocol.  The dumb protocol uses plain HTTP, but doesn't
   support incremental updates -- each pull re-downloads the entire pack
   file.  The smart protocol allows the client to specify the version it
   has, and the version it wants:


      0054want 31f1c37dfa1bf983e4d67e06fac28e8e6f
      00093bd7884 HEAD@{1}
      0032have e68fe437718c37155c7e3e5f4a3ff17c4f476940
      0000


   We can express this with HTTP Versioning as:


      Request:

         GET /repo/readme.md
         Version: "31f1c37dfa1bf983e4d67e06fac28e8e6f"
         Parents: "e68fe437718c37155c7e3e5f4a3ff17c4f476940"


   This expresses aspects of the "smart" git protocol over plain HTTP.


4.3.  Resumable uploads protocol

   Resource Versioning semantics enable efficient implementation of
   resumable uploads, providing an alternative perspective to
   [Resumable Upload].

   To initiate an upload, the client specifies the Version-Type and the
   expected final version using the Current-Version header:

      Request:

         PUT /something
         Current-Version: "abwejf-900"
         Version-Type: peer-counter; bytestream
         Content-Length: 900

         <binary data of length 900>

   For a successful upload, the server responds as usual:

      Response:

         200 OK

   If the upload is interrupted, the client can query the server's
   current state:

      Request:

         HEAD /something
         Parents: "abwejf-0"

   The server's response determines the client's next action:

   A. Upload complete:

      Response:

         200 OK
         Parents: "abwejf-0"
         Version: "abwejf-900"

   B. Partial upload:

      Response:

         206 Partial Content
         Parents: "abwejf-0"
         Version: "abwejf-400"

   C. No upload progress:

      Response:

         416 Range Not Satisfiable

   Based on the response, the client proceeds as follows:

   - Case A: Upload is complete, no further action needed.
   - Case B: Resume the upload from the last received byte:

      Request:

         PUT /something
         Current-Version: "abwejf-900"
         Parents: "abwejf-400"
         Content-Range: bytes 400-900/900
         Content-Length: 500

         <binary data from 400-900>

   - Case C: Restart the upload from the beginning.

   This protocol leverages general version semantics, allowing servers
   implementing HTTP Resource Versioning with the "bytestream"
   Version-Type to inherently support resumable uploads.


4.4.  Distributed collaborative editing

   This versioning system can also support full CRDT and OT
   collaborative editing features (when used with other extensions such
   as [Braid-HTTP]), allowing every URL to gain the functionality of
   Google Docs.

   The [Braid-Text] project implements a very efficient style of this.
   When you first load a resource, a server provides it as a single
   version:


      Request:

         GET https://braid.org/test
         Accept: text/plain
         Subscribe: true

      Response:

         HTTP/1.1 209 Multiresponse

         HTTP/1.1 200 OK
         Version: "2agvvzgccrq-5"
         Version-Type: peer-counter; text-runs
         Merge-Type: simpleton
         Content-Length: 12

         Hello world!


   Updates are expressed as a stream of patches:


      Response (continued):

         HTTP/1.1 200 OK
         Version: "4590r8uwm63-18"
         Parents: "2agvvzgccrq-5"
         Content-Length: 1
         Content-Range: text [12:12]

         :

         HTTP/1.1 200 OK
         Version: "4590r8uwm63-19"
         Parents: "4590r8uwm63-18"
         Content-Length: 1
         Content-Range: text [13:13]

         )


   This versioning system supports multiple [Merge-Types], and they can
   even co-exist simultaneously for the same resource.  For instance,
   braid-text supports two merge-types simultaneously:

     - The "simpleton" merge-type requires the server to rebase all
       edits for the client

     - The "dt" merge-type uses a fully peer-to-peer merge algorithm
       called Diamond-Types

   Clients can connect with either merge-type, and can even change
   merge-type on-the-fly -- the version history itself can be re-used.

 
4.5.  Improved Header Compression with runs

   A header compression scheme can leverage Version-Type patterns to
   significantly compress messages.  For example, consider the following
   scenario where 4 characters are inserted into a collaborative editor,
   requiring 479 bytes when uncompressed:

           PUT /some.txt
           Version: "3f84786c-57"
           Parents: "3f84786c-56"
           Content-Length: 1
           Content-Range: text 471:471

           a

           PUT /some.txt
           Version: "3f84786c-58"
           Parents: "3f84786c-57"
           Content-Length: 1
           Content-Range: text 472:472

           s

           PUT /some.txt
           Version: "3f84786c-59"
           Parents: "3f84786c-58"
           Content-Length: 1
           Content-Range: text 473:473

           d

           PUT /some.txt
           Version: "3f84786c-60"
           Parents: "3f84786c-59"
           Content-Length: 1
           Content-Range: text 474:474

           f


   Huffman Encoding (e.g. in HTTP's HPACK and QPACK) can compress these
   headers by identifying repeated strings and assigning them codes:

           U = "PUT /some.txt"
           W = "Version: \"3f84786c-{ }\""
           X = "Parents: \"3f84786c-{ }\""
           Y = "Content-Length: 1"
           Z = "Content-Range: text { }"

   This compression reduces the messages to:

           U
           W{57}
           X{56}
           Y
           Z{471:471}

           a

           U
           W{58}
           X{57}
           Y
           Z{472:472}

           s

           U
           W{59}
           X{58}
           Y
           Z{473:473}

           d

           U
           W{60}
           X{59}
           Y
           Z{474:474}

           f

   This initial compression reduces the 479 bytes to approximately 123
   bytes.
 
   Further compression is possible by recognizing that the numeric
   parameters in each header increment by 1 from the previous header.
   This allows us to take advantage of run-length encoding; specified as
   "Version-Type: peer-counter; text-runs".  We can thus compress the
   entire run of inserts using a new compression function, RUN(a, b, c):

           RUN(a, b, insertions) =
             for i, char in insertions
               return `
                 U
                 W{a+i}
                 X{a+i-1}
                 Y
                 Z{b+i:b+i}

                 char
               `

   Where the parameters are:

      a: Initial version number
      b: Initial content range
      insertions: String of characters to be inserted

   We could then compress the 479 bytes down to a single 20-byte message:

           RUN(57, 474, 'asdf')

   For even more compact representation, sacrificing human-readability,
   this can be encoded in 12 bytes:

           R57,474,asdf

   Further compression is possible by using variable-length integer
   encoding (such as LEB128 or Protocol Buffers' varint) for the numeric
   values.  This approach could potentially reduce the encoding to 7
   bytes for these 4 insertions, or just 1.46% of the uncompressed 479
   bytes.


4.6.  Run-Length Compression without Header Compression

   In practice, run-length compression can also be applied without
   relying on header compression.  By specifying:

           Version-Type: peer-counter; text-runs

   ...any peer can receive a series of N insertions as a single update
   and infer that the string in the update was composed of N separate
   insertions.  For instance, the previous example of four PUT requests
   can be compressed into a single update without any header
   compression:

           PUT /some.txt
           Version: "3f84786c-60"
           Parents: "3f84786c-56"
           Version-Type: peer-counter; text-runs
           Content-Length: 4
           Content-Range: text 471:474

           asdf

   This single request expresses the change from version 3f84786c-56 to
   3f84786c-60, implicitly including the three intermediate versions
   (3f84786c-57, 3f84786c-58, and 3f84786c-59).  Any client or server
   that understands "Version-Type: peer-counter; text-runs" can infer
   these intermediate versions when necessary by slicing the content
   "asdf" to the appropriate length for each version.

   For example:

      - Version 3f84786c-57 would contain "a"
      - Version 3f84786c-58 would contain "as"
      - Version 3f84786c-59 would contain "asd"
      - Version 3f84786c-60 would contain the full "asdf"

   This approach significantly reduces the number of HTTP requests and
   amount of data required for a series of small, consecutive inserts,
   while still allowing for precise version control and the ability to
   reconstruct any intermediate state.


5.  Acknowledgements

   This is derived from prior draft [Braid-HTTP] with authors:

     - Michael Toomim
     - Greg Little
     - Raphael Walker
     - Bryn Bellomy
     - Joseph Gentle

   And incorporates additional ideas from:

     - Rahul Gupta
     - Duane Johnson
     - Mitar Milutinovic
     - Paul Kuchenko


6.  Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].


7. IANA Considerations

7.1.  HTTP Header Registrations

   This document defines the following new HTTP headers, which should be
   added to the "Permanent Message Header Field Names" registry at
   <https://www.iana.org/assignments/message-headers>:


      Header Field Name: Version
      Protocol: http
      Status: standard
      Reference: This document

      Header Field Name: Parents
      Protocol: http
      Status: standard
      Reference: This document

      Header Field Name: Version-Type
      Protocol: http
      Status: standard
      Reference: This document

      Header Field Name: Current-Version
      Protocol: http
      Status: standard
      Reference: This document


   Additionally, this new status code should be added to the "HTTP
   Status Codes" registry at
   <https://www.iana.org/assignments/http-status-codes>:


      Value: 432
      Description: Version Not Found
      Reference: This document


7.2.  Version Type Registry

   The "Version Type Registry" defines the namespace for the version type
   names and refers to their corresponding specifications.  The registry
   will be created and maintained at
   <http://www.iana.org/assignments/version-types>.


7.2.1.  Procedure

   Registration of a Version Type MUST include the following fields:

   o  Type name

   o  Required parameters

   o  Optional parameters

   o  Description

   o  Security considerations

   o  Interoperability considerations

   o  Obsolete/Non-obsolete status

   o  Published specification

   o  Person & email address to contact for further information

   Values to be added to this namespace require IETF Review (see
   [RFC8126], Section 4.1).


7.2.2.  Version Type Registrations

7.2.2.1.  The peer-counter Version-Type

   The "peer-counter" Version-Type specifies that each Event ID is a
   Lamport timestamp, of the form:

      Version: "<peer>-<counter>"

   Or:

      Version: "<peer>-<counter>"; text-runs
      Version: "<peer>-<counter>"; bytestream

   It is guaranteed that, for any peer, the counter will always increase
   in subsequent versions.  Therefore, any two Event IDs from the same
   peer can be compared in time just by examining their counters.


7.2.2.1.1.  The "text-runs" modifier

   The modifier "text-runs" further constrains the behavior of the
   counter to enable run-length encoding.  Specifically, for each
   inserted set of characters, the counter is constrained to be set to
   the number of unicode codepoints that have been inserted; and for
   every deleted set of characters, the counter is constrained to
   represent the number of unicode codepoints that have been deleted.

   Furthermore, it defines that intermediate versions can be inferred,
   between any explicitly transmitted version, by assuming that for any
   insertion, all characters are inserted one-by-one, left-to-right, by
   unicode codepoint; and for any deletion, all characters are deleted
   right-to-left, by unicode codepoint.


7.2.2.1.2.  The "bytestream" modifier

   The "bytestream" modifier specifies that the resource can be
   considered as an append-only bytestream:

      Version-Type: peer-counter; bytestream

   Each <counter> then specifies that the number of bytes in the
   resource is equal to <counter> at time <peer>-<counter>.

   For example, "x82ha-344" indicates "the resource state after peer
   `x82ha` appended 344 bytes".

   This approach creates a direct correspondence between time and
   space: each version increment represents one additional byte in the
   stream.


7.2.3.  Comments on Version Type Registrations

   Comments on registered Version Types may be submitted by members of
   the community to the IANA at iana@iana.org.  These comments will be
   reviewed by the Version Types reviewer and then passed on to the
   "owner" of the Version Type if possible.  Submitters of comments may
   request that their comment be attached to the Version Type
   registration itself; if the IANA, in consultation with the Version
   Types reviewer, approves, the comment will be made accessible in
   conjunction with the type registration.


7.2.4.  Change Procedures

   Once a Version Type has been published by the IANA, the owner may
   request a change to its definition.  The same procedure that would be
   appropriate for the original registration request is used to process
   a change request.

   Version Type registrations may not be deleted; Version Types that are
   no longer believed appropriate for use can be declared OBSOLETE; such
   Version Types will be clearly marked in the list published by the
   IANA.

   Significant changes to a Version Type's definition should be
   requested only when there are serious omissions or errors in the
   published specification.  When review is required, a change request
   may be denied if it renders entities that were valid under the
   previous definition invalid under the new definition.

   The owner of a Version Type may pass responsibility to another person
   or agency by informing the IANA; this can be done without discussion
   or review.

   The IESG may reassign responsibility for a Version Type.  The most
   common case of this will be to enable changes to be made to types
   where the author of the registration has died, moved out of contact,
   or is otherwise unable to make changes that are important to the
   community.


8.  Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.
   

9. Security Considerations

   Version IDs may reveal information about the structure and activity
   of a resource's editors.  For instance, the "peer-counter"
   Version-Type encodes a peer identifier and a monotonically
   increasing counter, from which an observer can infer who is editing
   and how frequently.  Servers that expose version history SHOULD
   apply the same access control to versioned requests as they do to
   current-state requests, and SHOULD consider whether version
   identifiers themselves leak information that the resource body does
   not.

   A client requesting a range of version history (via Parents and
   Version headers together) could probe for the existence of versions
   it is not authorized to see.  Servers MUST NOT reveal version
   history to clients that are not authorized to access the resource.
   A server MAY respond with 403 Forbidden or 404 Not Found rather
   than 432 Version Not Found if acknowledging the existence of a
   version would itself constitute an information leak.

   Requesting a large range of version history could require
   significant server resources to assemble and transmit.  Servers
   SHOULD impose limits on the size of version history responses and
   MAY respond with 413 Content Too Large if a request would exceed
   those limits.  Servers MAY also rate-limit version history requests.

   As described in Section 4, a versioning-unaware intermediary may
   cache a historical version and serve it in response to a request
   for a different version.  If the resource is access-controlled,
   this could result in a client receiving a version of the resource
   it was not meant to see -- for instance, a version predating the
   revocation of sensitive content.  Origin servers SHOULD include
   "Vary: version, parents" in responses, and SHOULD consider adding
   "Cache-Control: no-store" or "Cache-Control: private" to
   versioned responses containing sensitive content.

   Since any peer can generate version IDs, a malicious client could
   craft version IDs that collide with or mimic another peer's IDs.
   This could corrupt version history or cause a server to
   misattribute edits.  Systems where version history integrity is
   important SHOULD validate version IDs against their expected
   Version-Type format and SHOULD treat version IDs from untrusted
   clients as opaque, unverified claims rather than trusted
   identifiers.


10.  Authors' Addresses

   For more information, the authors of this document are best contacted
   via Internet mail:

   Michael Toomim
   Invisible College, Berkeley
   2053 Berkeley Way
   Berkeley, CA 94704

   EMail: toomim@gmail.com
   Web:   https://invisible.college/@toomim


11.  References

11.1.  Normative References

   [RFC2119]           "Key words for use in RFCs to Indicate
                       Requirement Levels", RFC 2119.

   [RFC8126]           "Guidelines for Writing an IANA Considerations
                       Section in RFCs", RFC 8126.

   [RFC9651]           "Structured Field Values for HTTP", RFC 9651.

   [RFC9110]           "HTTP Semantics", RFC 9110.

   [Braid-HTTP]        draft-toomim-httpbis-braid-http-04

   [Merge-Types]       draft-toomim-httpbis-merge-types-00

   [Updates]           draft-toomim-httpbis-updates-[TBD]

   [Multiresponse]     draft-toomim-httpbis-multiresponse-[TBD]

   [Range-Patch]       draft-toomim-httpbis-range-patch-00

   [Resumable Upload]  draft-ietf-httpbis-resumable-upload


11.2.  Informative References

   [XHR]      Van Kesteren, A., Aubourg, J., Song, J., and R. M.
              Steen, H.  "XMLHttpRequest", September 2019.
              <https://xhr.spec.whatwg.org/>

   [SSE]      Hickson, I.  "Server-Sent Events", W3C Recommendation,
              February 2015.
              <https://www.w3.org/TR/2015/REC-eventsource-20150203/>

   [Braid-Text] <https://github.com/braid-org/braid-text>

   [RFC7089]  "HTTP Framework for Time-Based Access to Resource States
              -- Memento",  RFC 7089.

   [RFC3253]  "Versioning Extensions to WebDAV (Web Distributed Authoring
              and Versioning)", RFC 3253.

   [RFC5829]  "Link Relation Types for Simple Version Navigation between
              Web Resources", RFC 5829.