doc/OONI/Backend.md

+= Backend =
+
+The OONI Backend (or OONIB) will mainly accomplish two tasks: assisting probes in running tests (TestHelper), collecting reports from OONI-probes or third party censorship related testing systems (Reports, PacketCapture)
+
+== Test Helpers ==
+
+This backend infrastructure will be distributed and will run at least the following services:
+
+ * UDP and TCP Echo ([wiki:doc/OONI/Backend/TCPUDPEcho])
+ * Two way traceroute helper ([wiki:doc/OONI/Tests/TwoWayTraceroute])
+ * HTTP Server ([wiki:doc/OONI/Backend/HTTPServer])
+ * DNS resolver ([wiki:doc/OONI/Backend/DNSResolver])
+
+
+== Reporting system ==
+
+The reporting system will expose an HTTP RESTful API over HTTPS or HTTPO (a.k.a. HTTP/.onion). This API will allow probes that are interested in sending a report to an OONIB node to do so.
+
+
+=== REST API spec ===
+
+'''/report/do'''
+
+Responsible for creating and updating reports.
+
+'':POST''
+
+Creates a new report with the input
+
+{{{
+
+
+* Request
+
+          {'software_name': 'XXX',
+           'software_version': 'XXX',
+           'test_name': 'XXX',
+           'test_version': 'XXX',
+           }
+
+          Optional:
+            'test_helper': 'XXX'
+            'client_ip': 'XXX'
+
+* Response
+  
+  {'backend_version': 'XXX', 'report_id': 'XXX'}
+
+}}}
+
+
+''Required parameters''
+
+software_name: This is a string specifying the name of the software that is submitting a report (for example "OONI-probe")
+
+software_version: This is a string representing the version number of the software submitting the report
+
+test_name: This is the name of the test for which the report is being submitted
+
+test_version: This is the version of the test for which a report is being created
+
+''Optional Parameters''
+
+test_helper: specifies which test helper we are interested in using
+
+client_ip: is required when using test helpers to allow the matching up of client submitted reports with backend generated reports in OONIB.
+
+
+'':PUT''
+
+Update an already existing report.
+
+{{{
+  {'report_id': 'XXX',
+   'report': 'XXX'
+  }
+}}}
+
+
+'''/report/pcap'''
+
+This is the async pcap reporting system. It requires the client to have created a report
+already, but can work independently from test progress.
+
+
+'''/testhelper/'''
+
+This part of the API is used for signaling with the Test helper backend
+
+
+'''/controlchannel/'''
+
+This part of the API is used for configuring the control channel part of the backend.
+