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>