Query API Endpoints - Differentiating GET and POST methods

[pkutaj]

• The aim of this issue📝 share findings from #00029271 - I seems to be that the documentation VS consoleUI are inconsistent
• The documentation URL: https://clickhouse.com/docs/cloud/get-started/query-endpoints
• In the example section, the documentation contains a screenshot of a bit poor quality (possible to OCR the content, but not easiest) with the request...

curl -H "Content-Type: application/json" -X POST -s --user $KEY_ID:$KEY_SECRET $YOUTUBE_ENDPOINT_PATH --data-raw '{"queryVariables": {"year": 2010}, "format": "JSONEachRow"}'

...having a POST method with query variables in a JSON of a body of the request

• The Share Query button in SQL console explose only GET method with query variables in query parameters in the URL e.g.

curl -H "Content-Type: application/json" -s --user '<key_id>:<key_secret>' 'https://queries.clickhouse.cloud/run/4ac39097-2d8d-4a27-85d1-fca179708a04?format=JSONEachRow&param_year=<value>'

• If I follow the docs and use the POST method which in the following case would be

curl -H "Content-Type: application/json" -X POST -s --user $CLICKHOUSE_API_KEY_ID:$CLICKHOUSE_API_SECRET 'https://queries.clickhouse.cloud/run/4ac39097-2d8d-4a27-85d1-fca179708a04' --data-raw '{"queryVariables": {"year": 2010}, "format": "JSONEachRow"}'

• There is no distinction between the GET and the POST in the documentation
• The docs provide only a screenshot of the command, we should clarify the syntax of the body of the POST request
• This is what seems to be required for the body of a POST request

{
    "queryVariables": {
        "<query_variable_name_1>": <query_variable_value_1>,
        "<query_variable_name_2>": <query_variable_value_2>,
        // ... more query variables ...
    },
    "format": "<output_format_name>"
}

• Not sure if we do not need to include an exemplary curl POST also to the sql console

curl -H "Content-Type: application/json" \
     -X POST -s \
     --user <YOUR_CLICKHOUSE_API_KEY_ID>:<YOUR_CLICKHOUSE_API_SECRET> \
     'https://queries.clickhouse.cloud/run/<YOUR_QUERY_ID>' \
     --data-raw '{
         "queryVariables": {
             "<QUERY_VARIABLE_NAME_1>": <QUERY_VARIABLE_VALUE_1>,
             "<QUERY_VARIABLE_NAME_2>": <QUERY_VARIABLE_VALUE_2>
             // ... add more query variables as needed ...
         },
         "format": "<OUTPUT_FORMAT_NAME>"
     }'

Thanks!

[Blargian]

@pkutaj, sorry for the delay in getting to this. I've opened #4499 to hopefully address this. I've updated the screenshots to be consistent with how SQL console currently is, and also added a note about GET vs POST request along with some examples of GET request in addition to the POST request examples. Also some improvements to make this document easier to read.