What are Query Parameters?
Query parameters are parameters attached to the end of a URL and separated from the URL by a question mark (?). The section before the question mark is the path parameter, and the section after the question mark is the query. The path parameter defines the resource location, while the query parameter defines sort, pagination, or filter operations. The user's input (the query) is passed as a variable in the query parameter.
Query Parameter Example
For example, in `https://www.google.com/search?q=abstract%20api`, we have a standard Google search, with the user input `abstract%20api` being passed as a variable via the query parameter `q=`.
We can pass multiple variables with the `&` symbol separating parameters, forming a query string.
For example, if we search `abstract api` in the search box at `www.google.com`, the result URL is a monstrous string:
`https://www.google.com/search?q=abstract+api&rlz=1C1CHBF_enUS923US923&oq=abstract+api&aqs=chrome..69i57j0i10i433j0j0i10i433j0i10l6.1705j0j7&sourceid=chrome&ie=UTF-8`
If you look closely at this URL, you can see the `&` symbol separating the queries from eachother, and joining them into the query string. If you open the search request with your browser's developer tools, you will see the composite parts of this long string, like `q: abstract api` (our query), `oq: abstract api` (the actual string we typed into Google before resorting to auto-correct), and `sclient: gws-wiz` (our search engine).
What Can I Do with Query Parameters?
You might have noticed in the above example that our Google search is a GET request, with an HTTP response code like any other REST API request. Can we use query parameters in our REST API requests to endpoints? You bet we can!
Query Parameter API Example
Let's say we want to call a weather API for our [daily surf report](https://idratherbewriting.com/learnapidoc/docapis_new_endpoint_to_doc.html):
What do we see in this GET request?
- `/surfreport/beachID` `/surfreport` is the endpoint, and `beachID` is the path parameter. Path parameters are part of the endpoint and are [required](https://swagger.io/docs/specification/describing-parameters/).
- `?` is where our query string begins.
- `days=3` is a query parameter (`days`) that is taking the argument `3` to sort the surf report retrieved from the API into results from the next three days.
- `units=metric` is a query parameter that displays our results in Metric units.
- `time=1400` is a query parameter that displays results at time 1400.
- `&` is joining our individual query parameters into one query string.
API Query Parameter Description
There are some other elements that go into a query parameter description that aren't shown in the example above. One important parameter is `required`, which when set to `true` means the parameter is required. Path parameters are always required, but query parameters are optional.
Conclusion
Query parameters allow you to sort and filter data pulled from APIs, instead of having to sort it computationally, or even worse, having the user look for it. Imagine your API call above consumed all of the surf report and just printed it to a website: the user might as well purchase a newspaper, and this is an inefficient usage of computing resources and bandwidth. While path parameters show your program where to look, query parameters describe how to look.
