API & webhooks

Sample GET REST API Request: Query Parameters with curl

Run a reproducible curl GET with encoded query parameters, capture its status and body separately, and check empty results without changing the request method.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Make the sample request reproducible

A useful sample GET includes the target URL, query parameters, expected response shape and expected HTTP status. A bare URL can conceal an encoding mistake or depend on browser state that another person does not share. Use synthetic data and a local or authorized endpoint while developing the example.

Consider a fictional notes collection with q and limit parameters. The request searches for the literal phrase river & rail and asks for at most two items. The ampersand belongs inside the search value; it must not become a separator that starts another parameter.

Let curl encode the query values

curl --get --silent --show-error \
  --header "Accept: application/json" \
  --data-urlencode "q=river & rail" \
  --data-urlencode "limit=2" \
  --dump-header response-headers.txt \
  --output response-body.json \
  --write-out "%{http_code}" \
  https://example.com/notes

The address is a placeholder for the API you intend to test. The command uses shell line continuation as shown for a POSIX-style shell; use one line or the appropriate continuation syntax in another shell. On Windows, invoke curl.exe when necessary to select the actual curl program.

The curl GET option places these data arguments into the query. The encoding option protects reserved characters in each value. Do not pre-encode the same text and then encode it again unless the contract intentionally requires a literal percent-encoded string.

Interpret the three outputs separately

The response body is saved in response-body.json, the received header block in response-headers.txt, and the final HTTP status is written to standard output. A JSON filename does not guarantee that the server actually returned valid JSON, so inspect Content-Type and parse the saved body.

A successful transfer exit code is not identical to a successful application status. By default, curl can complete a readable HTTP error response successfully as a transfer. Record the printed status and decide whether that status is expected for the fixture.

For this collection contract, a successful empty result might be {"items":[]}. A readable 401 with an error object is a different outcome. Do not treat every file containing JSON as a successful list response.

Preserve the server's status even when its error body fails to parse; a parsing problem should not erase that diagnostic.

Check values at the receiving boundary

In a local fixture, log the parsed q and limit values without logging credentials. Assert that q is exactly river & rail and that limit is the expected string or parsed integer under the server's contract. This proves the request construction, rather than only inspecting how the command looks.

Repeat with a search containing a plus sign or Unicode text. A plus sign that becomes a space, or a percent sign that is interpreted twice, can change the query while still producing a syntactically valid URL. Keep the original and received values in the test evidence.

Preserve the intended GET semantics

The GET reference explains that the method requests a representation. Do not replace this command with a POST merely because another tutorial sends JSON, and do not rely on an undocumented GET body to carry these query values.

Likewise, using HEAD changes the request. It can help inspect headers in a separate investigation, but it does not verify the collection's response body. Keep the method fixed while testing parameter encoding and expected item selection.

Check a second query and an invalid limit

A complete small fixture should include two distinct successful searches, a search with no matches and a limit rejected by the service. Assert the exact returned identifiers or order, not only an items property. Ensure the second saved output replaces the first instead of reading an older file.

The REST API Testing Tool can reproduce a supported request in a browser, subject to its origin and credential constraints. Compare its URL and response with the curl capture, and explain any environment difference before treating the results as equivalent.