Query String Parameters

When you need to add query string parameters to the URL of a request, halchemy makes it easy. You use the with parameters method. This method takes a dictionary/object of parameters and their values. Here are some examples:

root = api.root.get()

# get the first page of customers, 100 per page
customers = api.follow(root).to('customers').with_parameters({'max_results':100,'page':1}).get()
# adds ?max_results=100&page=1 to the URL

const root = await api.root.get()

// get the first page of customers, 100 per page
let customers = await api.follow(root)
    .to('customers')
    .withParameters({ max_results: 100, page: 1 })
    .get()
// adds ?max_results=100&page=1 to the URL

root = api.root.get

# get the first page of customers, 100 per page
customers = @api.follow(root)
                .to("customers")
                .with_parameters({ "max_results" => 100, "page" => 1 })
                .get
# adds ?max_results=100&page=1 to the URL

NOTE

with parameters does not simply append the query string the URL. That would not work if the URL already had query string parameters. Instead, halchemy ensures all query string parameters are properly merged.

Table of Examples

Typically, a query string contains one or more name value pairs, e.g. ?name=John&age=50. Halchemy provides a sophisticated way to pass simple or complex parameters in the query string.

Here is a list of parameter examples: the dictionary/object you pass to with parameters and the query string that is added to the URL.

Parameters	Query String	Comments
{"name":"John"}	name=John
{"age": 50}	age=50
{"name":"John Doe"}	name=John+Doe	HTML forms notation for spaces in simple strings (i.e. plus sign for spaces).
{ "name":"John", "address":"123 Main St", "age":50 }	name=John&address=123+Main+St&age=50
{"pretty":null}	pretty	A name without a value.
{"pretty":true}	pretty=true
{"list":["a","b","c"]}	list=a&list=b&list=c	A value that is a list. See below for how to configure serializing such lists.
{ "name":"John", "address": { "street":"10 Main", "city":"York" } }	name=John&address.street=10+Main &address.city=York	Nested objects (i.e. address in this case). Uses dot notation for each field.
{"where":"{\"account\":\"1234\"}"}	where=%7B%22account%22%3A%221234%22%7D	Sending an object as a string - i.e. wrap it in quotes.
{"percent":"100%"}	percent=100%25	The reserved character is urlencoded to %25.
{"special":"$&+,/:;=?@"}	special=%24%26%2B%2C%2F%3A%3B%3D%3F%40	All special characters are urlencoded.
{ "emoji":"😀", "chinese":"中文" }	emoji=%F0%9F%98%80 &chinese=%E4%B8%AD%E6%96%87	You can include Unicode in your parameters values.