commit 7695a43969611482f8182110b2bc4acc9d011c75 Author: Arturo Filastò arturo@filasto.net Date: Fri Feb 5 15:14:49 2016 +0100
Align version of the oonib specification to the version of the backend.
* Update to add support for the extra keys required by the new JSON data format --- oonib.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 20 deletions(-)
diff --git a/oonib.md b/oonib.md index 88ab62a..90d7b99 100644 --- a/oonib.md +++ b/oonib.md @@ -1,7 +1,7 @@ # oonib specification
-* version: 0.2 -* date: 2013-07-04 +* version: 1.3.0 +* date: 2016-02-05 * author: Arturo Filastò, Aaron Gibson
This document aims at providing a functional specification of oonib. At the @@ -85,6 +85,11 @@ The HTTP request it performs is: `string` the Authonomous System Number of the network the test is related to prefixed by "AS" (ex. "AS1234")
+ 'probe_cc': + NEW since oonibackend 1.3 + `string` the two-letter country code of the probe as defined in + ISO3166-1 alpha-2 or ZZ when undefined (ex. "IT") + 'test_name': `string` the name of the test performing the network measurement. In the case of ooni-probe this is the test filename without the ".py" @@ -93,16 +98,26 @@ The HTTP request it performs is: 'test_version': `string` the version of the test peforming the network measurement.
- 'input_hashes': + 'data_format_version': + NEW since oonibackend 1.3 + `string` that must be either "json" or "yaml" to identify the format + of the content. + + 'start_time': + NEW since oonibackend 1.3 + `float` seconds since epoch in UTC of when the measurement was started. + + 'input_hashes': (optional) `list` of hex encoded sha256sum of the contents of the inputs we are using for this test. This field is required if the collector backend only accepts certain inputs (that is it has a collector policy). For more information on policies see section 2.3.
- 'test_helper': + 'test_helper': (optional) `string` the name of the required test_helper for this test.
'content': + DEPRECATED since oonibackend 1.3 (optional) `string` it is optionally possible to create a report with already some data inside of it.
@@ -111,6 +126,12 @@ The HTTP request it performs is: test requires a test_helper the probe should inform oonib of it's IP address. We need to know this since we are not sure if the probe is accessing the report collector via Tor or not. + + 'format': + `string` that must be either "json" or "yaml" to identify the format + of the content. + New since version 0.2.0 of the data format or 1.2 of the backend. + }
When a report is created the backend will respond with a report identifier @@ -119,7 +140,7 @@ backend software like follows:
`Status Code: 201 (Created)`
- { +{
'backend_version': `string` containing the version of the backend @@ -130,7 +151,12 @@ backend software like follows: 'test_helper_address': (conditional) `string` the address of a test helper that the client requested.
- } + 'supported_formats': + NEW since oonibackend 1.3 + `list` of strings detailing what are the supported formats for + submitted reports. Can either be "json" or "yaml". + +}
The report identifier allows the probe to update the report and it will be contructed as follows: @@ -139,7 +165,7 @@ contructed as follows:
A report identifier can be for example:
- 1912-06-23T101234Z_AS1234_ihvhaeZDcBpDwYTbmdyqZSLCDNuJSQuoOdJMciiQWwAWUKJwmR + 19120623T101234Z_AS1234_ihvhaeZDcBpDwYTbmdyqZSLCDNuJSQuoOdJMciiQWwAWUKJwmR
If the report does not match the collector policy it will not create a report or return a valid report_id. @@ -169,7 +195,8 @@ the report by referencing it by id:
`PUT /report`
- { +``` +{
'report_id': `string` the report identifier @@ -178,7 +205,13 @@ the report by referencing it by id: `string` content to be added to the report. This can be one or more report entries in the format specified in df-000-base.md
- } + 'format': + `string` that must be either "json" or "yaml" to identify the format + of the content. + New since version 0.3 of the data format or 1.2 of the backend. + +} +```
This method is deprecated, because it is not proper usage of HTTP request methods. PUT should only be used for operations that are idempotent. @@ -189,13 +222,20 @@ New collectors should use the following format for updating reports:
`POST /report/$report_id`
- { +``` +{
content: `string` content to be added to the report. This can be one or more report entries in the format specified in df-000-base.md
- } + 'format': + `string` that must be either "json" or "yaml" to identify the format + of the content. + New since version 0.3 of the data format or 1.2 of the backend. + +} +```
### 2.3.1.3 Closing a report
@@ -233,14 +273,13 @@ This will list all the available decks. This will return the descriptor for the specified deck
``` -{ - 'name': "the name of the deck", - 'description': "a description of the deck", - 'version': "the deck version number", - 'author': "the author name and email address in the format John Doe john@example.com", - 'date': "the deck creation time in ISO 8601", +{ + 'name': "the name of the deck", + 'description': "a description of the deck", + 'version': "the deck version number", + 'author': "the author name and email address in the format John Doe john@example.com", + 'date': "the deck creation time in ISO 8601", } - ```
#### GET /deck/$deck_id/yaml @@ -269,14 +308,13 @@ This will list all the available inputs: This will return the descriptor for the specified input
``` -{ +{ 'name': "the name of the input", 'description': "a description of the input", 'version': "the input version number", 'author': "the author name and email address in the format John Doe john@example.com", 'date': "the input creation time in ISO 8601", } - ```
#### GET /input/$input_id/file