Basic

Asking in the URL

I wanted only the recent records and I pulled everything then filtered in my code. The URL can carry the filter, so the server sends only what you asked for.

What you will see

[{"match": "hello world"}]

About 1 min of reading

Quick check

Before this new lesson, one small question about the lesson you just finished. Recall it, do not look it up.

Try It

Put a filter in the URL and let the server do the narrowing.

Ask for a limited page via the query. The server returns only those records.

curl -s 'https://api.example/users?limit=1'

Before you run it, say out loud what it will print. Then open the answer.

What it prints

[{"id": 1}]

Let curl build and escape the query for you.

curl -sG -d limit=1 -d since=2026-01-01 https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints

[{"id": 1}]

A value with a space must be escaped. curl does it, a hand-built URL might not.

curl -sG -d 'q=hello world' https://api.example/search

Before you run it, say out loud what it will print. Then open the answer.

What it prints

[{"match": "hello world"}]

If you build the URL by hand and write q=hello world, the space breaks the query. Use a builder or escape it. This is the top silent bug in hand-built URLs.

Data Flow

The query string carries key=value pairs in the URL, the server reads them to narrow the result, and values are percent-encoded so the structure is not broken.

1 Query holds key=value pairs

↓

2 Server reads them to filter

↓

3 Values are percent-encoded

↓

4 Only the subset returns

Why this works

Query is part of the URL

The query string is key=value pairs after a ?, joined by &. It is the cheapest way to ask for a subset, because it needs no body and no special method. A GET with a query is still a GET, still cacheable.

Values must be escaped

A URL cannot hold a raw space, &, or = in a value, because those mean structure. Percent-encoding replaces them. A library that builds the query escapes for you; hand-built strings are where the escaping bug lives.

Examples

The query string

GET /users?since=2026-01-01&limit=10 HTTP/1.1

After the path, a ? starts the query and & joins pairs. Each pair is a parameter the server can act on.

Encode the value

?q=hello%20world

A space in a URL is written %20. Characters that mean something in a URL get escaped. Forget it and the query splits wrong.

Send params with curl

curl -G -d since=2026-01-01 -d limit=10 https://api.example/users

-G with -d builds the query string for you and escapes the values. You did not hand-encode.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← JSON as the payload

Previous Lesson

JSON as the payload

Next Lesson

Proving who you are

Proving who you are →