Query Parameters

Query parameters are the name/value pairs that follow the ? in a URL. Burl lets you add them with the request_builder::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

request_builder::query appends a name/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

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

request_builder::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