Explaining the relationship between the POST method and query parameters in HTTP

The aim of this page📝 is to explain the relationship between POST HTTP methods and query parameters, clarifying common misconceptions and demonstrating real-world usage patterns. My wrong understanding was query params are only for the GET method and that POST gets a payload only in its BODY. TIL — Wrong! Some notes…

• POST requests can technically include query parameters — there’s nothing in the HTTP specification that forbids combining POST with query parameters in the URL, though it’s not the typical pattern

• Primary data goes in the request body, not query parameters — POST requests are designed to send their main payload in the request body, making them fundamentally different from GET requests that rely on query parameters

• Security considerations favor request bodies over URLs — query parameters appear in server logs, browser history, and referrer headers, while request bodies don’t get logged or cached the same way, making them safer for sensitive data

• Data structure complexity drives the choice — request bodies can handle complex nested JSON/XML structures and different content types, while query parameters are limited to flat key-value pairs

• Common POST + query parameter patterns include API versioning, metadata flags, and optional parameters — examples include POST /api/v1/users?version=2.1 or POST /upload?overwrite=true

• Size limitations exist but aren’t the primary concern — URLs have practical limits around 2KB in browsers, but structural and security issues become problematic before size constraints

• Semantic clarity matters for API design — POST body indicates “here’s data to process/store” while query parameters typically mean “here are filters/options for the request”

• Real-world example demonstrates practical usage — ClickHouse query API uses query parameters for formatting (format=JSON) and parameterized queries (param_catId=value) while sending the actual SQL in the POST body

• Template syntax can construct dynamic URLs — the pattern ${(event.payload.request.otherData["formField78"])!} represents template expression syntax where values are extracted from event objects and substituted into URLs before making HTTP requests

• Parameterized queries prevent SQL injection — using param_ prefixed query parameters that get safely substituted into SQL placeholders like {catId:String} provides secure parameter passing

• Best practices align with separation of concerns — well-designed APIs send primary data in POST body and reserve query parameters for metadata, filtering, or optional flags rather than core payload data

• Template engines and workflow tools commonly generate dynamic URLs — systems like workflow automation tools or serverless functions often construct ClickHouse or database API URLs dynamically based on form submissions or webhook events

Code Examples

Basic POST with query parameters:

POST /api/users?action=create&source=mobile
Content-Type: application/json

{"name": "John", "email": "john@example.com"}

Complex data structure comparison:

# Awkward with query params:
POST /users?name=John&email=john@example.com&address.street=123%20Main&address.city=Boston

# Natural with body:
POST /users
{"name": "John", "email": "john@example.com", "address": {"street": "123 Main", "city": "Boston"}}

ClickHouse parameterized query:

URL: POST /run/query-id?format=JSON&param_catId=12345
Body: SELECT * FROM cats WHERE cat_id = {catId:String}

Template syntax example:

# Before template processing:
https://queries.clickhouse.cloud/run/query-id?format=JSON&param_catId=${(event.otherdata["field99"])!}

# After template processing:
https://queries.clickhouse.cloud/run/query-id?format=JSON&param_catId=12345