Query Parameters

Query parameters are the key-and-value pairs that follow the ? in a URL. Burl lets you add them with the builder’s query function, and they can equally be written straight into the URL you pass to the verb function, the two approaches produce the same request.

The query Function

query appends a key-and-value pair to the URL’s query string, percent-encoding both:

auto r = co_await client.get("https://example.com/search")
    .query("category", "shoes")
    .query("color", "blue")
    .send();
// GET /search?category=shoes&color=blue

Each call adds another parameter, so the order of query calls is the order they appear in the query string.

Parameters in the URL

You do not have to use query at all: parameters written directly into the URL you supply are treated identically. These two requests are equivalent:

// added through query
auto a = co_await client.get("https://example.com/search")
    .query("category", "shoes")
    .query("color", "blue")
    .send();

// written into the supplied URL
auto b = co_await client.get("https://example.com/search?category=shoes&color=blue")
    .send();

Combining Both

query appends to whatever the URL already carries:

auto r = co_await client.get("https://example.com/search?category=shoes")
    .query("color", "blue")
    .send();
// GET /search?category=shoes&color=blue

Next Steps

Edit this Page