[onionoo/master] Add version field. - tor-commits

31 Aug 2014

commit b19c5d57a2a638e4280490e6c3888bcc65c767b3
Author: Karsten Loesing karsten.loesing@gmx.net
Date:   Sun Aug 31 08:45:18 2014 +0200
Add version field.
Suggested by iwakeh in #12905.  Implements that ticket.
---
 .../torproject/onionoo/server/ResponseBuilder.java |    5 +-
 web/protocol.html                                  |   83 +++++++++++++++++++-
 2 files changed, 84 insertions(+), 4 deletions(-)

diff --git a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
index 676a039..c951fd3 100644
--- a/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
+++ b/src/main/java/org/torproject/onionoo/server/ResponseBuilder.java
@@ -69,8 +69,11 @@ public class ResponseBuilder {
     return this.charsWritten;
   }
+  private static final String PROTOCOL_VERSION = "1.0";
+
   private void writeRelays(List<SummaryDocument> relays, PrintWriter pw) {
-    String header = "{"relays_published":"" + relaysPublishedString
+    String header = "{"version":"" + PROTOCOL_VERSION
+        + "",\n"relays_published":"" + relaysPublishedString
         + "",\n"relays":[";
     this.charsWritten += header.length();
     pw.write(header);
diff --git a/web/protocol.html b/web/protocol.html
index 0a123ba..9194c63 100644
--- a/web/protocol.html
+++ b/web/protocol.html
@@ -120,7 +120,7 @@ Only file a bug report if this problem persists.
</ul>
-<h4>Protocol changes</h4>
+<h4>Protocol versions</h4>
 <p>
 There are plenty of reasons why we may have
 to change the protocol described here.
@@ -135,8 +135,25 @@ If you want to be informed of upcoming protocol changes, subscribe to the
 mailing list.
 </p>
-<p>The Onionoo API is described by resource types and available methods
-below.</p>
+<p>All responses contain a "version" string that indicates whether clients
+know whether they can parse the document or not.
+Version strings consist of a major and a minor version number.
+The major version number is raised when previously required fields are
+dropped or turned into optional fields, when request parameters or
+response documents are removed, or when there are structural changes.
+The minor version number is raised when new fields, request parameters, or
+response documents are added or optional fields are dropped.
+If clients support the same major version given in a response but only a
+lower minor version, they should be able to parse the document but may not
+understand all fields.
+If clients support a lower major version, they should not attempt to parse
+a document, because there may be backward-incompatible changes.
+The following versions have been used in the past six months:</p>
+
+<ul>
+<li><strong>1.0</strong>: First assigned version number on August 31,
+2014.</li>
+</ul>
</div> <!-- box -->
@@ -476,6 +493,16 @@ Summary documents contain the following fields:</p>
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>
@@ -629,6 +656,16 @@ Details documents contain the following fields:
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>
@@ -1404,6 +1441,16 @@ Bandwidth documents contain the following fields:
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>
@@ -1567,6 +1614,16 @@ Weights documents contain the following fields:
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>
@@ -1762,6 +1819,16 @@ Clients documents contain the following fields:
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>
@@ -1930,6 +1997,16 @@ Uptime documents contain the following fields:
 <ul class="properties">
<li>
+<font color="blue"><b>version</b></font>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+<font color="blue">Added on August 31, 2014.</font>
+</p>
+</li>
+
+<li>
 <b>relays_published</b>
 <code class="typeof">string</code>
 <span class="required-true">required</span>

    