4. Request Parameters

Variables in Postman

Postman allows you to save values as variables to reuse them and easily hid sensitive info like API keys. We will use a variable to replace our URL so that we don’t have to type that repeatedly. Once a variable is defined, you can access its value using double curly brace syntax like this: .

In Postman, you can quickly create a variable by selecting text. Below the animation is a step-by-step breakdown of how to set your variable:

1. Go to the “get books request in your Collection.
2. With your cursor, select the entire base URL of the API (https://library-api.postmanlabs.com). Do not include the slash (/) after .com.

3. Click Set as variable to save the base URL to a variable.

   

4. Click Set as a new variable:

   

5. Name your variable “baseURL” and select “Collection” as the scope, then click Set variable:

   

Now that the variable is set, you can access the value anywhere in your collection by typing . If you hover over you will see that its current value is set to https://library-api.postmanlabs.com.

Save and Send the request!

Where are my variables?

You can find Collection variables in your collection: click your collection, then the Variables tab, from where you can view and edit them:

Note that are there two columns:

1. INITIAL VALUE - the value initialy set when someone forks or imports your collection. If you share your collection with others, they will see this value, so don’t put any secrets here!
2. CURRENT VALUE - Postman always resolves the variable to this value. This is local to your Postman account, and not public. It is good to keep secrets like API keys ONLY in this column and not include them in the INITIAL VALUE column.

Query parameters

Remember that the minimum ingredients you need to make a request are:

• A request method
• A request URL

Some APIs allow you to refine your request further with key-value pairs called query parameters.

Query parameter syntax

Query parameters are added to the end of the path. They start with a question mark (?), followed by the key-value pairs in the format <key>=<value>. For example, this request might fetch all photos that have landscape orientiation: GET https://some-api.com/photos?orientation=landscape.

If there are multiple query parameters, each is separated by an ampersand (&). For instance, this request contains two query parameters to specify the orientation and size of the photos to be returned: GET https://some-api.com/photos?orientation=landscape&size=500x400.

Search Google - with query parameters!

Try pasting this URL into your browser or as a GET request in Postman to make a Google search for “Postman”.

If you use Postman, click on the Preview tab in the response to view the rendered HTML.

This request adds a search term as a query parameter: q=postman (q refers to query here) to the GET /search path on Google’s server. Because the parameter is in our request, the server returns an HTML document that is a search results page with hits for “Postman”. The search bar is pre-populated with our query “Postman”:

When to use query parameters?

The answer is always: read the API documentation! Sometimes, query parameters are optional and allow you to add filters or extra data to your responses. Sometimes, they are required in order for the server to process your request. APIs are implemented differently to fulfill different needs.

The Postman Library API v2 allows you to add optional query parameters on requests to GET /books in order to filter the books that come back in reponse.

Task: Search books by genre

Let’s try to filter our book’s results only to show us fiction books. The API allows us to add query parameters to a GET /books request to filter the results, as shown under Params:

Get all fiction books

1. In Postman, inside the Postman Library API v2 Collection you made, hover over the “get books” request, click the three dots icon that appears, and then select Duplicate to create a copy of the request.

2. Rename this second request to “get fiction books”. You can hover on the collection name in the right pane and click the edit icon that appears:

   

3. Using the Params tab, add a query parameter with a key genre and value fiction to the get fiction books request. Notice how Postman syncs the request URL in real time, adding the question mark (?) automatically to mark the start of query parameters:

   

4. Save and Send your request. You should get a 200 OK response with an array of book objects - but only books with the fiction genre:

   

Task: Multiple query parameters

As a librarian, you will need to help visitors find available books (not checked out). Let’s add a second query parameter to GET /books only to list books where the checkedOut property is false.

1. In the same get fiction books request, in the Params tab, add a second query parameter with a key checkedOut and value false:

   

2. Save and Send your request. You should get a 200 OK response with an array of only fiction books that are not checked out or an empty array ([]) if there are no fiction books available:

   

Path Variable

Another way of passing request data to an API is via path variables, aka path parameters. A path variable is a dynamic section of a path and is often used for IDs and entity names, such as usernames.

Path Variable syntax

The path variable comes immediately after a slash in the path. For example, the GitHub API allows you to search for GitHub users by providing a username in the path in pace of {username}: GET https://api.github.com/users/{username}. Making this API call with a value for {username} will fetch data about that user. You can have multiple path variables in a single request, such as this endpoint for getting a user’s GitHub code repo: GET https://api.github.com/repos/{owner}/{repoName}.

Path vs. query parameters

At first, it is easy to confuse these two parameter types.

Path Variable	Query parameters
ex: /books/abc123	: /books?search=borges&checkedOut=false
Located directly after a slash in the path. It can be anywhere on the path.	Located only at the end of a path, right after a question mark ?
Accepts dynamic values	Accepts defined query keys with potentially dynamic values
* Often used for IDs or entity names	* Often used for options and filters

These are just conventions. Some APIs might ask you to pass an ID or username in a query parameter like this: /users?username=getpostman.

When to use path variables?

Always read the API documentation! If a path parameter is required, the documentation will mention it. Some API documentation uses colon syntax to represent a wildcard in the path like: /users/:username, while some use curly braces such as /users/{username}. They both mean the same thing: that part of the path is dynamic.

Task: Get a book by id

Someone keeps visiting the library daily, asking whether “Ficciones” by Jorge Luis Borges is available. When you fetched all the books in the library, you may have noticed that each book has a unique id value which can always be used to identify the book, even if its other properties are changed. Since the person keeps asking about “Ficciones”, you have jotted down that the unique id of this book is 29cd820f-82f9-4b45-a7f4-0924111b5b89.

Get a book by id

According to the API documentation, we can get a specific book by hitting the path GET /book/:id, where we replace the :id with the book’s id.

1. Hover on your Postman Library API v2 Collection, click the three dots, select Add request, and name it “get book by id”.

2. Make sure the request method is set to GET, and paste in this endpoint as the request URL: /books/:id.

   Postman automatically adds a Path Variables editor in the Params tab of the request for any path variables in the request URL prefixed with a colon (:).

   

3. In the Params tab, paste the id for “Ficciones” (29cd820f-82f9-4b45-a7f4-0924111b5b89) as the value for the path variable id. Make sure not to add any whitespace around the id value.

   

4. Save and Send your request. You should get a 200 OK response with a single JSON object that represents the “Ficciones” book:

   

Debugging request in the Postman Console

You used Postman’s path variable helper in the Params tab of the request to add a path variable nicknamed :id to the request URL in a human-friendly way. Postman replaces :id with the value your specify for id in the Path Variables editor. You can always view the raw request sent to the API by opening the Postman Console in the lower left of Postman. All request you make, and their responses are logged in the Postman Console:

You can see that Postman has inserted the book id as a path parameter in place of the :id placeholder when making the request. If you run into any erros when making API calls, always check the Postman Console and ensure the raw request was sent as expected. A common error is adding accidental whitespace in your query or path parameter values.