From 7ea127b7ea4e54757107833141b9d125f19139d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Tue, 18 Feb 2025 09:57:30 +0100 Subject: [PATCH 01/11] Start adding details about dynamic inputs in OONI Run v2 --- backends/bk-005-ooni-run-v2.md | 168 +++++++++++++++++++++++++-------- 1 file changed, 130 insertions(+), 38 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index 561a008f..ac300615 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -125,12 +125,24 @@ An OONI Run link descriptor is a JSON file with the following semantics: // `array` provides a JSON array of tests to be run. "nettests":[{ - // (optional) `array` provides a JSON array of tests to be run. + // (optional) `array` provides a JSON array of inputs for the specified test. "inputs": [ "https://example.com/", "https://ooni.org/" ], + // (optional) `array` provides a richer JSON array containing targets for the specified experiment. + // One of either `inputs` or `targets` can be specified, but not both. + "targets": [ + "input": "https://example.com/", + "extra": { + "category_code": "HUMR", + } + ], + + // (optional) string used to specify during creation what is the label for targets to use. + "targets_name": "websites_list_prioritized", + // (optional) `map` options arguments provided to the specified test_name // // Note: this field is currently experimental. A future version of the specification @@ -139,18 +151,6 @@ An OONI Run link descriptor is a JSON file with the following semantics: "HTTP3Enabled": true }, - // (optional) `map` settings which are sent to probe_services for retrieving the inputs vector - // It's possible to reference user configured settings by accessing the - // $settings special variable. - // In particular the content of the backend_options will be sent to the /api/v1/check-in call nested - // under the relative test_name. - // - // Note: this field is currently experimental. A future version of the specification - // may modify the field name or its semantics if we discover it needs changes. - "backend_options": { - "category_codes": "$settings.category_codes" - }, - // (optional) `bool` indicates if this test should be run as part of autoruns. Defaults to true. // // Note: this field is currently experimental. A future version of the specification @@ -166,21 +166,33 @@ An OONI Run link descriptor is a JSON file with the following semantics: "test_name": "web_connectivity" }, { "test_name": "openvpn", - "backend_options": { - "provider": "riseupvpn" - }, + "targets": [ + "input": "https://foo.com/", + "extra": { + "provider": "riseupvpn", + } + ], }] } ``` -In particular values starting with the `$settings` prefix should be mapped -based on user-configured preferences in the app. (Note also that this is -currently an experimental feature that we may change in the future.) +In reality there are two different views onto an OONI Run link descriptor. One +is the view from the perspective of the creator and owner of the link, the +second is from the perspective of measurement applications that need to consume +these links. -Currently the following `$settings` are defined: +The reason for this is that certain target lists need to be generated +dynamically and at runtime, while the parameters for generating these dynamic +links are specified by the creator of the link. -* `$settings.category_codes` should be replaced with the list of category codes - the user has enabled (ex. `["HUMR", "NEWS"]`. +A prime example of this would be the OONI Run link for the stock OONI Websites +card. The OONI Run descriptor, as specified from the link creator, is saying +"run the test-lists with weights applied based on coverage", while the mobile +application will then receive a prioritized and sorted list which will change +every time a new run is performed. + +To achieve this we need 2 different views on the link, one for the creation +phase (`target_name`) and another for the retrieval phase (`targets`). Based on the above specification it would be possible to re-implement the cards for the OONI Probe dashboard as follows. @@ -197,20 +209,17 @@ dashboard as follows. "nettests": [ { - "options": { - "MaxRuntime": "$settings.max_runtime", - }, - "backend_settings": { - "category_codes": "$settings.category_codes" - }, + "targets": [ + "input": "https://example.com/", + "extra": { + "category_code": "HUMR", + } + ], "is_manual_run_enabled": true, "is_background_run_enabled": false, "test_name": "web_connectivity" }, { - "backend_settings": { - "category_codes": "$settings.category_codes" - }, "is_manual_run_enabled": false, "is_background_run_enabled": true, "test_name": "web_connectivity" @@ -358,7 +367,7 @@ authentication should be handled. When you `CREATE` a new OONI RUN link, the client sends a HTTP `POST` request conforming to the following: -`POST /api/v2/oonirun` +`POST /api/v2/oonirun/links` ```JavaScript { @@ -401,6 +410,11 @@ request conforming to the following: } ``` +Moreover it's possible to specify `targets` as rich JSON structure or +`target_name` indicating the name of the target list which will result in the +target list being generated dynamically. + +`target`, `target_name` and `inputs` are mutually exclusive. ### Response status code @@ -465,7 +479,7 @@ To update an OONI Run Link, the client issues a request compliant the same as th Below we list the extra fields that are settable from the edit request that are not settable during CREATE. -`PUT /api/v2/oonirun/{ooni_run_link_id}` +`PUT /api/v2/oonirun/links/{ooni_run_link_id}` ```JavaScript { @@ -510,8 +524,8 @@ following JSON body: ## 4.3 GET the OONI Run descriptor -This operation is performed by OONI Probe clients to retrieve the descriptor of -a certain OONI Run link given the ID. +This operation is performed by OONI Probe clients to retrieve the latest +revision for a descriptor of a certain OONI Run link given the ID. As such, this request does not require any authentication. @@ -519,7 +533,7 @@ As such, this request does not require any authentication. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/{oonirun_link_id}` +`GET /api/v2/oonirun/links/{oonirun_link_id}` ### Response status code @@ -541,7 +555,85 @@ following JSON body: } ``` -## 4.4 LIST the OONI Run descriptors +Note: for dynamically generated run links, this view will only return the +`target_name` and not the `targets` list. + +## 4.4 GET the OONI Run full descriptor by revision + +This operation is performed by OONI Probe clients to retrieve the descriptor of +a certain OONI Run link given the ID and revision + +As such, this request does not require any authentication. + +### Request + +To retrieve an OONI Run link descriptor, the client issues a request compliant with: + +`GET /api/v2/oonirun/links/{oonirun_link_id}/full-descriptor/{revision}` + +### Response status code + +Same as 4.3 GET the OONI Run descriptor + +### Response body + +Same as 4.3 GET the OONI Run descriptor + +Note: for dynamically generated run links, this view will only return the +`target_name` and not the `targets` list. + +## 4.4 GET the OONI Run engine descriptor revision + +This operation is performed by OONI Probe clients to retrieve the engine descriptor of +a certain OONI Run link given the ID and revision + +As such, this request does not require any authentication. + +This method is used to return just the nettests, revision and date_created +sections of a descriptor to be used by the measurement engine. + +When the specified OONI Run link contains dynamic targets, it will return the +generated `targets` list and hence every request might return a different target +list. + +### Request + +To retrieve an OONI Run link descriptor, the client issues a request compliant with: + +`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}` + +Upon receiving this request, the OONI Run backend: + +1. SHOULD check whether the `${oonirun_link_id}` exists and return 404 if it does + not. + +2. if everything is okay, returns `200` to the client (see below). + +### Response body + +In case of success (i.e. `200` response), the OONI Run Service MUST return the +following JSON body: + +```JavaScript +{ + "revision": "1", + "date_created": "" + "nettests": [ + { + // See CREATE response format for other fields + "targets": [ + "input": "https://example.com/", + "extra": { + "category_code": "HUMR", + } + ], + "test_name": "web_connectivity" + } + ] +} +``` + +## 4.7 LIST the OONI Run descriptors This operation is performed by users of the OONI Run platform to list all the existing OONI Run links. @@ -551,7 +643,7 @@ Authentication for this endpoint is optional. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun_links?only_latest=true&only_mine=true&include_archived=true` +`GET /api/v2/oonirun/links?only_latest=true&only_mine=true&include_archived=true` - `only_latest`, boolean flag to filter only by the latest revision of an OONI Run link. If unset or set to false, it will instead include all revisions as From 86c25cac854c2cd23c9dbbdf2d5a267cd6632357 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Tue, 18 Feb 2025 10:04:27 +0100 Subject: [PATCH 02/11] Add headers used to pass options to descriptor get request Question: do we want to use headers for this or should we instead make a new post handler which does these in the request body? That would be slightly more flexible if we would like to use this request to pass additional data as part of the first request. --- backends/bk-005-ooni-run-v2.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index ac300615..232e0a15 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -609,6 +609,20 @@ Upon receiving this request, the OONI Run backend: 2. if everything is okay, returns `200` to the client (see below). +A client should also include the following headers to allow the server to +properly generate dynamic target lists: + +* `X-OONI-ProbeCc`: Two letter, uppercase country code (eg. IT) +* `X-OONI-ProbeAsn`: ASN, two uppercase letters followed by number (eg. AS1234) +* `X-OONI-Platform`: platform name (eg. android) +* `X-OONI-SoftwareName`: software_name (eg. ooniprobe-android) +* `X-OONI-SoftwareVersion`: software_version (eg. 3.14.0) +* `X-OONI-NetworkType`: flag used to indicate the network type where the + measurement is run: 0 unknown, 1 for wifi, 2 mobile +* `X-OONI-Charging`: 1 yes, 0 no. Set only for devices with batteries. +* `X-OONI-RunType`: 1 timed, 0 manual +* `X-OONI-WebsiteCategoryCodes`: comma separated list of category codes that user has chosen to test (eg. NEWS,HUMR) + ### Response body In case of success (i.e. `200` response), the OONI Run Service MUST return the From 97552f0dc28461aa7de4f5cacb4f425f6d45b62b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Mon, 14 Apr 2025 15:50:05 +0200 Subject: [PATCH 03/11] Simplify headers for OONI Run v2.1 --- backends/bk-005-ooni-run-v2.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index 232e0a15..9033ebc4 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -19,7 +19,7 @@ Below are definitions for important components of the system: with the OONI Probe app installed allows the user to instrument their probe to run the nettests configured by the link creator. If the OONI Probe app is not installed, it will display a web page asking them to download the app. - + * **OONI Run descriptor** contains the metadata for a specific OONI Run link and the nettest definitions: what nettests should be run and how they should be configured (ex. what URLs should be tested) @@ -600,7 +600,7 @@ list. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}` +`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}?run_type={timed|manual}&is_charging={true|false}` Upon receiving this request, the OONI Run backend: @@ -611,17 +611,16 @@ Upon receiving this request, the OONI Run backend: A client should also include the following headers to allow the server to properly generate dynamic target lists: - -* `X-OONI-ProbeCc`: Two letter, uppercase country code (eg. IT) -* `X-OONI-ProbeAsn`: ASN, two uppercase letters followed by number (eg. AS1234) -* `X-OONI-Platform`: platform name (eg. android) -* `X-OONI-SoftwareName`: software_name (eg. ooniprobe-android) -* `X-OONI-SoftwareVersion`: software_version (eg. 3.14.0) -* `X-OONI-NetworkType`: flag used to indicate the network type where the - measurement is run: 0 unknown, 1 for wifi, 2 mobile -* `X-OONI-Charging`: 1 yes, 0 no. Set only for devices with batteries. -* `X-OONI-RunType`: 1 timed, 0 manual +* `X-OONI-NetworkInfo`: `, ()`, eg `AS1234,IT (wifi)` * `X-OONI-WebsiteCategoryCodes`: comma separated list of category codes that user has chosen to test (eg. NEWS,HUMR) +* `X-OONI-Credentials`: base64 encoded OONI anonymous credentials + +The the `platform`, `software_name`, `software_name`, `engine_name` and +`engine_version` are encoded inside of the `User-Agent` string using the following +format: +``` +/ () / () +``` ### Response body @@ -647,6 +646,13 @@ following JSON body: } ``` +Additionally, the `Vary` header should specify the list of headers that affect +the response body caching, which are all headers starting with the `X-OONI-` +prefix. + +The server might also return an updated version of the submitted anonymous +credentials using the `X-OONI-Credentials` header. + ## 4.7 LIST the OONI Run descriptors This operation is performed by users of the OONI Run platform to list all the existing OONI Run links. From ba441dbc6721d01b05201675cfaabf0153c1c624 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Thu, 8 May 2025 12:50:59 +0200 Subject: [PATCH 04/11] Update bk-005-ooni-run-v2.md Fix syntax of targets --- backends/bk-005-ooni-run-v2.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index 9033ebc4..d98569de 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -133,10 +133,11 @@ An OONI Run link descriptor is a JSON file with the following semantics: // (optional) `array` provides a richer JSON array containing targets for the specified experiment. // One of either `inputs` or `targets` can be specified, but not both. - "targets": [ - "input": "https://example.com/", - "extra": { - "category_code": "HUMR", + "targets": [{ + "input": "https://example.com/", + "extra": { + "category_code": "HUMR", + } } ], @@ -166,12 +167,12 @@ An OONI Run link descriptor is a JSON file with the following semantics: "test_name": "web_connectivity" }, { "test_name": "openvpn", - "targets": [ + "targets": [{ "input": "https://foo.com/", "extra": { "provider": "riseupvpn", } - ], + }], }] } ``` @@ -209,12 +210,12 @@ dashboard as follows. "nettests": [ { - "targets": [ + "targets": [{ "input": "https://example.com/", "extra": { "category_code": "HUMR", } - ], + }], "is_manual_run_enabled": true, "is_background_run_enabled": false, "test_name": "web_connectivity" @@ -634,12 +635,12 @@ following JSON body: "nettests": [ { // See CREATE response format for other fields - "targets": [ + "targets": [{ "input": "https://example.com/", "extra": { "category_code": "HUMR", } - ], + }], "test_name": "web_connectivity" } ] From 2a5b3a6825fdc514c61aff6f96cd5f6dccc4393f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Thu, 15 May 2025 18:59:13 +0200 Subject: [PATCH 05/11] Handle backward compatibility more gracefully * Drop targets and replace with `inputs_extra` * Cleanup some text --- backends/bk-005-ooni-run-v2.md | 83 ++++++++++++++-------------------- 1 file changed, 33 insertions(+), 50 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index d98569de..3230daf8 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -131,27 +131,15 @@ An OONI Run link descriptor is a JSON file with the following semantics: "https://ooni.org/" ], - // (optional) `array` provides a richer JSON array containing targets for the specified experiment. - // One of either `inputs` or `targets` can be specified, but not both. - "targets": [{ - "input": "https://example.com/", - "extra": { + // (optional) `array` provides a richer JSON array containing extra parameters for each input. + // If provided, the length of inputs_extra should match the length of inputs. + "inputs_extra": [{ "category_code": "HUMR", - } - } - ], + }], - // (optional) string used to specify during creation what is the label for targets to use. + // (optional) string used to specify during creation that the input list should be dynamically generated. The semantics of each string is up to the backend implementation. "targets_name": "websites_list_prioritized", - // (optional) `map` options arguments provided to the specified test_name - // - // Note: this field is currently experimental. A future version of the specification - // may modify the field name or its semantics if we discover it needs changes. - "options": { - "HTTP3Enabled": true - }, - // (optional) `bool` indicates if this test should be run as part of autoruns. Defaults to true. // // Note: this field is currently experimental. A future version of the specification @@ -167,11 +155,11 @@ An OONI Run link descriptor is a JSON file with the following semantics: "test_name": "web_connectivity" }, { "test_name": "openvpn", - "targets": [{ - "input": "https://foo.com/", - "extra": { + "inputs": [ + "https://riseup-vpn-address.com/" + ], + "inputs_extra": [{ "provider": "riseupvpn", - } }], }] } @@ -192,9 +180,6 @@ card. The OONI Run descriptor, as specified from the link creator, is saying application will then receive a prioritized and sorted list which will change every time a new run is performed. -To achieve this we need 2 different views on the link, one for the creation -phase (`target_name`) and another for the retrieval phase (`targets`). - Based on the above specification it would be possible to re-implement the cards for the OONI Probe dashboard as follows. @@ -210,11 +195,11 @@ dashboard as follows. "nettests": [ { - "targets": [{ - "input": "https://example.com/", - "extra": { - "category_code": "HUMR", - } + "inputs": [ + "https://example.com/" + ], + "inputs_extra": [{ + "category_code": "HUMR", }], "is_manual_run_enabled": true, "is_background_run_enabled": false, @@ -399,9 +384,10 @@ request conforming to the following: "https://example.com/", "https://ooni.org/" ], - "options": { - "HTTP3Enabled": true, - }, + "inputs_extra": [ + {}, + {} + ] "test_name": "web_connectivity" }, { @@ -411,11 +397,12 @@ request conforming to the following: } ``` -Moreover it's possible to specify `targets` as rich JSON structure or -`target_name` indicating the name of the target list which will result in the -target list being generated dynamically. - -`target`, `target_name` and `inputs` are mutually exclusive. +The `inputs_extra` field should can be a list of JSON objects, with each object +corresponding to an entry in the `inputs` list. This allows you to attach +additional metadata to each input. The `targets_name` field specifies the name +of a predefined target list that will be used to dynamically generate the inputs +list. This name must be recognized by the backend and agreed upon in advance +between the link creator and the backend system. ### Response status code @@ -556,9 +543,6 @@ following JSON body: } ``` -Note: for dynamically generated run links, this view will only return the -`target_name` and not the `targets` list. - ## 4.4 GET the OONI Run full descriptor by revision This operation is performed by OONI Probe clients to retrieve the descriptor of @@ -580,8 +564,8 @@ Same as 4.3 GET the OONI Run descriptor Same as 4.3 GET the OONI Run descriptor -Note: for dynamically generated run links, this view will only return the -`target_name` and not the `targets` list. +When the specified OONI Run link contains dynamic targets, the `inputs` list may +contain different targets. ## 4.4 GET the OONI Run engine descriptor revision @@ -593,9 +577,8 @@ As such, this request does not require any authentication. This method is used to return just the nettests, revision and date_created sections of a descriptor to be used by the measurement engine. -When the specified OONI Run link contains dynamic targets, it will return the -generated `targets` list and hence every request might return a different target -list. +When the specified OONI Run link contains dynamic targets, the `inputs` list may +contain different targets. ### Request @@ -635,11 +618,11 @@ following JSON body: "nettests": [ { // See CREATE response format for other fields - "targets": [{ - "input": "https://example.com/", - "extra": { - "category_code": "HUMR", - } + "inputs": [ + "https://example.com/" + ], + "inputs_extra": [{ + "category_code": "HUMR", }], "test_name": "web_connectivity" } From dd0de078e39ae4a73b8df044969dd8172aab5e3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20D=C3=ADaz?= Date: Fri, 23 May 2025 14:06:14 +0200 Subject: [PATCH 06/11] sync names with current backnd implementation --- backends/bk-005-ooni-run-v2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index 3230daf8..b866ce7c 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -647,13 +647,13 @@ Authentication for this endpoint is optional. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/links?only_latest=true&only_mine=true&include_archived=true` +`GET /api/v2/oonirun/links?only_latest=true&is_mine=true&is_expired=true` - `only_latest`, boolean flag to filter only by the latest revision of an OONI Run link. If unset or set to false, it will instead include all revisions as separate entries. -- `only_mine` , boolean flag to filter only the links of the logged in user. Will only work when the Authentication header is used. -- `include_archived` , boolean flag used to indicate if the listing should include archived links as well. +- `is_mine` , boolean flag to filter only the links of the logged in user. Will only work when the Authentication header is used. +- `is_expired` , boolean flag used to indicate if the listing should include archived links as well. ### Response status code From 819ba65fdb36784479ea9b49c528121ad6844949 Mon Sep 17 00:00:00 2001 From: Luis Diaz <41093870+LDiazN@users.noreply.github.com> Date: Mon, 2 Jun 2025 11:27:53 +0200 Subject: [PATCH 07/11] Update get ooni run engine descriptor revision - Move fields from headers to body - Move fields from query parameters to body - Mark fields for dynamic test lists calculation as required --- backends/bk-005-ooni-run-v2.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index b866ce7c..424a0946 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -584,8 +584,19 @@ contain different targets. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}?run_type={timed|manual}&is_charging={true|false}` - +`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}` +``` +{ + "is_charging" : true, // `bool` if the probe is charging or not + "run_type" : "manual", // `string` valid options: timed | manual + + // The following fields are required for the dynamic tests list calculation + "probe_cc" : "IT", // `string` country code of the probe + "probe_asn" : "AS1234", // `string` ASN for the probe, + "network_type" : "wifi", // `string` + "website_category_codes" : ["NEWS"], // `array` of strings with category codes used for filtering +} +``` Upon receiving this request, the OONI Run backend: 1. SHOULD check whether the `${oonirun_link_id}` exists and return 404 if it does @@ -595,11 +606,10 @@ Upon receiving this request, the OONI Run backend: A client should also include the following headers to allow the server to properly generate dynamic target lists: -* `X-OONI-NetworkInfo`: `, ()`, eg `AS1234,IT (wifi)` -* `X-OONI-WebsiteCategoryCodes`: comma separated list of category codes that user has chosen to test (eg. NEWS,HUMR) + * `X-OONI-Credentials`: base64 encoded OONI anonymous credentials -The the `platform`, `software_name`, `software_name`, `engine_name` and +The `platform`, `software_name`, `software_name`, `engine_name` and `engine_version` are encoded inside of the `User-Agent` string using the following format: ``` From 620ec4f938046a9f13c607f35197097c10cc3f47 Mon Sep 17 00:00:00 2001 From: Luis Diaz <41093870+LDiazN@users.noreply.github.com> Date: Mon, 2 Jun 2025 11:50:41 +0200 Subject: [PATCH 08/11] Change get engine description to POST method --- backends/bk-005-ooni-run-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index 424a0946..c12532eb 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -584,7 +584,7 @@ contain different targets. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}` +`POST /api/v2/oonirun/links/{oonirun_link_id}/engine-descriptor/{revision}` ``` { "is_charging" : true, // `bool` if the probe is charging or not From 3f9bc6265e53cc796302af8ecb51008cd3521a79 Mon Sep 17 00:00:00 2001 From: Luis Diaz <41093870+LDiazN@users.noreply.github.com> Date: Mon, 2 Jun 2025 12:19:41 +0200 Subject: [PATCH 09/11] Add remarks for dynamic tests lists calculation --- backends/bk-005-ooni-run-v2.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index c12532eb..e2be6199 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -397,7 +397,7 @@ request conforming to the following: } ``` -The `inputs_extra` field should can be a list of JSON objects, with each object +The `inputs_extra` field should be a list of JSON objects, with each object corresponding to an entry in the `inputs` list. This allows you to attach additional metadata to each input. The `targets_name` field specifies the name of a predefined target list that will be used to dynamically generate the inputs @@ -409,9 +409,10 @@ between the link creator and the backend system. Upon receiving a request to create a link, the API will respond: 1. SHOULD fail with `4xx` if the request body does not parse, it is not a JSON object, - any required field is missing and/or if any present field has an invalid value. + any required field is missing and/or if any present field has an invalid value. In particular, + note that it will error when `targets_name` and `inputs` are provided at the same time in any nettest -2. if everything is okay, MUST return a `200` response. +3. if everything is okay, MUST return a `200` response. ### Response body @@ -543,6 +544,10 @@ following JSON body: } ``` +Note: This endpoint does not compute dynamic test lists. As a result, +nettests with `target_name` will always have an empty `inputs` field. + + ## 4.4 GET the OONI Run full descriptor by revision This operation is performed by OONI Probe clients to retrieve the descriptor of @@ -639,6 +644,11 @@ following JSON body: ] } ``` +Note: While nettests can't include both `inputs` and `target_name` during creation, +this endpoint may show both since the backend dynamically populates +`inputs` based on `target_name`. + +The backend computes dynamic test lists only for this request. Other requests will return an empty `inputs` list. Additionally, the `Vary` header should specify the list of headers that affect the response body caching, which are all headers starting with the `X-OONI-` From 0d67f0331025e1b3f1850e17b71deed221d9a59d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Mon, 2 Jun 2025 15:46:45 +0200 Subject: [PATCH 10/11] Update backends/bk-005-ooni-run-v2.md --- backends/bk-005-ooni-run-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index e2be6199..d978f078 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -412,7 +412,7 @@ Upon receiving a request to create a link, the API will respond: any required field is missing and/or if any present field has an invalid value. In particular, note that it will error when `targets_name` and `inputs` are provided at the same time in any nettest -3. if everything is okay, MUST return a `200` response. +2. if everything is okay, MUST return a `200` response. ### Response body From 48c655ed458ac2bbf89f67c49a23bafec5631e21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Arturo=20Filast=C3=B2?= Date: Mon, 2 Jun 2025 15:50:07 +0200 Subject: [PATCH 11/11] `only_latest` is not implemented --- backends/bk-005-ooni-run-v2.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/backends/bk-005-ooni-run-v2.md b/backends/bk-005-ooni-run-v2.md index d978f078..8cd14043 100644 --- a/backends/bk-005-ooni-run-v2.md +++ b/backends/bk-005-ooni-run-v2.md @@ -667,11 +667,8 @@ Authentication for this endpoint is optional. To retrieve an OONI Run link descriptor, the client issues a request compliant with: -`GET /api/v2/oonirun/links?only_latest=true&is_mine=true&is_expired=true` +`GET /api/v2/oonirun/links?is_mine=true&is_expired=true` -- `only_latest`, boolean flag to filter only by the latest revision of an OONI - Run link. If unset or set to false, it will instead include all revisions as - separate entries. - `is_mine` , boolean flag to filter only the links of the logged in user. Will only work when the Authentication header is used. - `is_expired` , boolean flag used to indicate if the listing should include archived links as well.