summaryrefslogtreecommitdiff
path: root/core/api-common.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2020-03-30 15:05:45 +0530
committerFlorian Dold <florian.dold@gmail.com>2020-03-30 15:05:45 +0530
commit293b3d55d8cd6cf946bb4e86bfe8ef743156838b (patch)
tree0006d49d08a1c05c684cfc98bbb544f4bae75bcb /core/api-common.rst
parentcca20e01dac3f9efd464742b1b930abe85ca8f70 (diff)
downloaddocs-293b3d55d8cd6cf946bb4e86bfe8ef743156838b.tar.gz
docs-293b3d55d8cd6cf946bb4e86bfe8ef743156838b.tar.bz2
docs-293b3d55d8cd6cf946bb4e86bfe8ef743156838b.zip
document protocol version ranges
Diffstat (limited to 'core/api-common.rst')
-rw-r--r--core/api-common.rst53
1 files changed, 53 insertions, 0 deletions
diff --git a/core/api-common.rst b/core/api-common.rst
index 44d4eb00..5fafacb9 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -121,6 +121,59 @@ handle the error as if an internal error (500) had been returned.
type_actual?: string;
}
+-----------------------
+Protocol Version Ranges
+-----------------------
+
+Some of the Taler services (e.g. exchange, merchant, bank integration API)
+expose the range of API versions they support. Clients in turn have an API
+version range they support. These version ranges are written down in the
+`libtool version format <https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html>`__.
+
+A protocol version is a positive, non-zero integer. A protocol version range consists of three components:
+
+1. The ``current`` version. This is the latest version of the protocol supported by the client or service.
+2. The ``revision`` number. This value is not to be interpreted by the client/server, but serves
+ purely as a comment. Each time a service/client for a protocol is updated while supporting the same
+ set of protocol versions, the revision should be increased.
+3. The ``age`` number. This non-zero integer identifies with how many previous protocol versions this
+ implementation is compatible. An ``age`` of 0 implies that the implementation only supports
+ the ``current`` protocol version. The ``age`` must be less or equal than the ``current`` protocol version.
+
+To avoid confusion with semantic versions, the protocol version range is written down in the following format:
+
+.. code:: none
+
+ current[:revision[:age]]
+
+The angle brackets mark optional components. If either ``revision`` or ``age`` are omitted, they default to 0.
+
+Examples:
+
+* "1" and "1" are compatible
+* "1" and "2" are **incompatible**
+* "2:0:1" and "1:0:0" are compatible
+* "2:5:1" and "1:10:0" are compatible
+* "4:0:1" and "2:0:0" are **incompatible**
+* "4:0:1" and "3:0:0" are compatible
+
+.. note::
+
+ `Semantic versions <https://semver.org/>`__ are not a good tool for this job, as we concisely want to express
+ that the client/server supports the last ``n`` versions of the protocol.
+ Semantic versions don't support this, and semantic version ranges are too complex for this.
+
+.. warning::
+
+ A client doesn't have one single protocol version range. Instead, it has
+ a protocol version range for each type of service it talks to.
+
+.. warning::
+
+ For privacy reasons, the protocol version range of a client should not be
+ sent to the service. Instead, the client should just use the two version ranges
+ to decide whether it will talk to the service.
+
.. _encodings-ref: