doc/protocol-versioning.txt
author Edward Pilatowicz <edward.pilatowicz@oracle.com>
Mon, 16 Sep 2013 21:26:31 -0700
changeset 2945 24196b483cc6
parent 145 08bee7fd13f6
permissions -rw-r--r--
17461187 packagemanager displays unexpected error message
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
145
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     1
For obvious compatibility reasons, the over-the-wire protocol needs to be
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     2
versioned.  Since we're using HTTP, it makes sense to simply version the
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     3
URLs used.
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     4
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     5
The scheme is pretty simple:
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     6
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     7
    http://host:port/operation/version(/extra)?
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     8
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
     9
where "version" is a simple integer.
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    10
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    11
Open questions:
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    12
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    13
  - Are there operations where we don't want to require a version?
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    14
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    15
  - Is there a use for a "300 Multiple Choices" HTTP return code?
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    16
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    17
  - If we always try the client-optimal version first and then back off
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    18
    linearly, we'll want to cache the version that succeeded so we don't
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    19
    spend all of our time trying versions that don't exist.
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    20
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    21
  - Alternatively, we can call "versions" to find out what versions the
08bee7fd13f6 Add versioning to the protocols
Danek Duvall <danek.duvall@sun.com>
parents:
diff changeset
    22
    server supports for each operation, and cache that.