Understanding Path Variables and Query Parameters in HTTP Requests

Imagine that you’re here:

If you’re like me and grew up in the 90s, a wave of nostalgia probably just hit you pretty hard.

But you might be wondering, what does this trip down memory lane have to do with path variables and query parameters in HTTP requests?

Stay with me; I’m about to connect the dots. :)

I’m currently in the process of building an API for an internal tool at Studio Faye. While defining the necessary endpoints in the controller, I found myself grappling with when to use a path variable and when to use a query parameter for my HTTP requests. In this article, I’ll share what I’ve learned and how to use each of them in a RESTful way.

Before diving in, let me first clarify what path variables and query parameters are.

Imagine we have a database filled with people, their home states, and their email addresses. We can perform four primary operations on the people in the database: adding new people, retrieving people, updating their email addresses, or deleting them.

To execute any of these operations, we need to instruct the database accordingly. This is where path variables and query parameters come into play.

Path variables and query parameters are both ways to tell a database what, or in this case who, we’re looking for.

Path variables are part of the URL itself and are enclosed in curly braces. On the other hand, query parameters are attached to the end of a URL and are followed by a question mark.

Here are some examples:

Now that we understand that both path variables and query parameters help us communicate with a database, how do we know which one to use?

Let’s take a step back to Chuck E. Cheese’s and head straight to my favorite childhood spot: the ball pit!

Imagine all these balls are in a database. Each ball has a unique ID and a color. If we wanted to retrieve all the yellow balls, we would use a query parameter. Why? Because query parameters act as filters. Remember, they come after a question mark.

It would look like this:

This query parameter tells the database to filter all the yellow balls.

But what if, out of all the balls, there was only one unique silver ball in the entire pit and we wanted to retrieve only that one?

In that case, we would use a path variable. Whenever you need to identify a specific ball (or resource), it’s considered a RESTful practice to use a path variable.

Here is an example:

This path variable tells the database to retrieve only the silver ball, based on its ID.

We see path variables and query parameters every time we shop online at places such as Amazon.

Every single Amazon product has a unique id. Based on Amazon’s Product Advertising API documentation, in order to retrieve a single product, here is a sample GET request:

GET https://webservices.amazon.com/paapi5/product/{productID}

Because this request is geared towards a single product, you can see that a path variable is used.

So, the best way to remember it is: when dealing with a single, specific item, like the unique silver ball, use a path variable. When filtering by attributes like color, use a query parameter.

Below, you’ll find a chart highlighting the key differences, along with annotations used in Spring Boot.

I hope you’ve enjoyed this article, and thank you for reading! I’d love to hear your feedback. Please feel free to share your thoughts in the comments below.

Avery