When should developers use the HTTP QUERY method instead of GET or POST in REST APIs?

The HTTP QUERY method is intended for situations where a request is safe (does not modify server state), idempotent, and requires a request body to express complex query criteria. It bridges the gap between GET, which is ideal for retrieval but poorly supports request bodies, and POST, which supports request bodies but is generally associated with state-changing operations.

Use QUERY when

Choose the QUERY method if all of the following apply:

• The operation only retrieves data and does not create, update, or delete resources.
• The query parameters are too large or complex to fit comfortably in a URL.
• The client needs to send structured JSON or another request body containing filters, sorting, pagination, or search criteria.
• You want the request semantics to clearly indicate a safe, read-only operation.

Example

Instead of encoding a complex search in the URL:

GET /products?category=Laptops&brand=Dell&minPrice=500&maxPrice=2000&features=ssd,16gb,backlit&page=1&sort=price

A QUERY request can move the criteria into the body:

QUERY /products
Content-Type: application/json

{
  "category": "Laptops",
  "brands": ["Dell", "HP"],
  "price": {
    "min": 500,
    "max": 2000
  },
  "features": [
    "SSD",
    "16GB RAM",
    "Backlit Keyboard"
  ],
  "page": 1,
  "sort": "price"
}

Use GET when

GET remains the best choice for standard resource retrieval.

Typical scenarios include:

• Fetching a single resource
• Listing resources with simple filters
• Bookmarkable or shareable URLs
• Browser-based navigation
• Requests that benefit from widespread caching

Example:

GET /users/123

or

GET /products?category=Books&page=2

Advantages

• Universally supported
• Easily cached
• URLs can be bookmarked and shared
• Works consistently with browsers and intermediaries

Use POST when

Use POST if the operation changes server state or represents an action rather than a pure query.

Examples include:

• Creating resources
• Uploading files
• Processing payments
• Submitting forms
• Triggering server-side jobs

POST /orders

or

POST /payments

POST may also be used for complex searches when broad compatibility is more important than expressing read-only semantics, since it is widely supported by clients, proxies, and API gateways.

Comparison

Practical examples

Use GET

• View a product
• Get a user profile
• Retrieve recent blog posts

GET /products/42

Use QUERY

• Advanced product search
• GIS or geospatial filtering
• Analytics queries with many dimensions
• Reporting with nested filter objects

QUERY /reports/sales

Body:

{
  "regions": ["North", "South"],
  "dateRange": {
    "from": "2026-01-01",
    "to": "2026-06-30"
  },
  "groupBy": [
    "month",
    "product"
  ]
}

Use POST

• Create an invoice
• Submit an order
• Start a data import
• Send a message

POST /orders

Current adoption considerations

Although the QUERY method provides clearer semantics for complex, read-only operations, its ecosystem support is still limited compared to GET and POST. Many HTTP clients, browsers, proxies, API gateways, and caching infrastructure do not yet fully recognize or optimize for QUERY. As a result:

• Prefer GET for simple retrieval operations.
• Use POST for state-changing operations and, when necessary, for complex searches that must work across today's HTTP infrastructure.
• Consider QUERY only if both your clients and server infrastructure explicitly support it and you want to distinguish complex read-only queries from actions that modify server state.