Path Parameters Vrs Query Parameters

I know for a fact that every seasoned web developer has, some time ago, struggled with grasping the differences between the two. I for example struggled with it until I fully understood the clear difference as a result of the experience I have gained from working on projects. Therefore, I have taken it upon myself to make sure web developers at any skill level reading this piece fully understand the differences and use cases of the two parameters.

Prerequisite

For me to achieve my goal of making sure every single person who reads this piece understands the topic in discussion I would like to make everything practical.

In making this practical the first thing I want to introduce you to is rapidapi. It is a site where you can get access to numerous collections of APIs for tests or projects. A user can sign up by creating an account. Upon signing up you get a rapidapi key which will be automatically included in all the requests you will make to any API at all you find over there.

Next, search for IMdb in the search panel or use this link. That is the API we will be using. Subscribe to it. There are other plans but the free plan is perfect for what we intend to do. This will give you access to test it out. You can check the API overview to learn more about the API. There are a couple of endpoints we will be using so brace yourself for the journey ahead.

API Overview

Guide to navigating API

Let’s try testing the GET Top 250 Movies endpoint to familiarize ourselves with the IMDb database and Rapidapi as a whole.

Your first task is to select the Movies section in the sidebar on the left and select the GET Top 250 Movies endpoint.

Selecting endpoint

If you had subscribed to the API earlier like I said you will get an option to test it.

Testing endpoint

Test it and observe the response that comes; a Json of movies. The response is quite lengthy to completely output it here but I am pretty sure if everything goes well you will have it at your end.

Notice that each movie has an IMDb id that starts with ‘tt’ and ends with some random numbers. That is the id of each movie present.

I will be defining what path and query parameters are while providing testing guidelines to improve understanding.

What is a Path Parameter?

A Path Parameter is a variable part of a URL that points to a specific resource in a collection. These resources are specific to the various entities in an application. For the IMdb API for instance there are entities like cast, movies, ratings, writers, directors, etc. Each one of them has a lot of resources. Recall the list of the top 250 movies that were returned with each movie having an id. If we were just interested in one movie, which endpoint would we have made our request to and what would our request url be like? Luckily for us, all our questions have already been answered because there is an endpoint to handle that. Let’s dive deep into that.

Now that you have experience in navigating your way around the API, select the GET Details for IMDb ID endpoint. The curl request looks like this;

curl --request GET 
 --url https://imdb236.p.rapidapi.com/imdb/{imdbId} 
 --header 'x-rapidapi-host: imdb236.p.rapidapi.com' 
 --header 'x-rapidapi-key: {rapidapi-key}'

The imdbId is the path parameter in this request. It identifies a particular movie resource in a vast collection of movie resources. Testing this request will return a response with all the details of the movie with the IMDb id.

{"id":"tt7631058","url":"https:\/\/www.imdb.com\/title\/tt7631058\/","primaryTitle":"The Lord of the Rings: The Rings of Power","originalTitle":"The Lord of the Rings: The Rings of Power","type":"tvSeries","description":"Epic drama set thousands of years before the events of J.R.R. Tolkien\u0027s \u0027The Hobbit\u0027 and \u0027The Lord of the Rings\u0027 follows an ensemble cast of characters, both familiar and new, as they confront the long-feared re-emergence of evil to Middle-earth.","primaryImage":"https:\/\/m.media-amazon.com\/images\/M\/MV5BNmVmZGQ2ZTctYzE4NC00YzkxLThhNjYtNGIyZjJmZGEwMjUzXkEyXkFqcGc@._V1_.jpg","contentRating":"TV-14","startYear":2022,"endYear":null,"releaseDate":"2022-09-01","interests":["Adventure Epic","Epic","Fantasy Epic","Sword \u0026 Sorcery","Action","Adventure","Drama","Fantasy"],"countriesOfOrigin":["US","NZ","CA"],"externalLinks":["https:\/\/www.facebook.com\/LOTRonPrime","https:\/\/www.instagram.com\/LOTRonPrime\/"],"spokenLanguages":["en"],"filmingLocations":["Auckland, New Zealand"],"productionCompanies":null,"budget":456000000,"grossWorldwide":null,"genres":["Action","Adventure","Drama"],"isAdult":false,"runtimeMinutes":null,"averageRating":6.9,"numVotes":416143,"directors":[{"id":"nm0104851","url":"https:\/\/www.imdb.com\/name\/nm0104851\/","fullName":"Charlotte Br\u00e4ndstr\u00f6m"},{"id":"nm3408764","url":"https:\/\/www.imdb.com\/name\/nm3408764\/","fullName":"Wayne Che Yip"},{"id":"nm0393776","url":"https:\/\/www.imdb.com\/name\/nm0393776\/","fullName":"Louise Hooper"},{"id":"nm1065402","url":"https:\/\/www.imdb.com\/name\/nm1065402\/","fullName":"Sanaa Hamri"},{"id":"nm1291105","url":"https:\/\/www.imdb.com\/name\/nm1291105\/","fullName":"J.A. Bayona"}],"writers":[{"id":"nm4259881","url":"https:\/\/www.imdb.com\/name\/nm4259881\/","fullName":"Patrick McKay"},{"id":"nm4260438","url":"https:\/\/www.imdb.com\/name\/nm4260438\/","fullName":"John D. Payne"},{"id":"nm0866058","url":"https:\/\/www.imdb.com\/name\/nm0866058\/","fullName":"J.R.R. Tolkien"},{"id":"nm2899027","url":"https:\/\/www.imdb.com\/name\/nm2899027\/","fullName":"Justin Doble"},{"id":"nm0128663","url":"https:\/\/www.imdb.com\/name\/nm0128663\/","fullName":"Jason Cahill"},{"id":"nm1112464","url":"https:\/\/www.imdb.com\/name\/nm1112464\/","fullName":"Gennifer Hutchison"},{"id":"nm4851331","url":"https:\/\/www.imdb.com\/name\/nm4851331\/","fullName":"Nicholas Adams"},{"id":"nm5403126","url":"https:\/\/www.imdb.com\/name\/nm5403126\/","fullName":"Stephany Folsom"},{"id":"nm5535928","url":"https:\/\/www.imdb.com\/name\/nm5535928\/","fullName":"Glenise Mullins"},{"id":"nm2256631","url":"https:\/\/www.imdb.com\/name\/nm2256631\/","fullName":"Helen Shang"}],"cast":[{"id":"nm6077056","url":"https:\/\/www.imdb.com\/name\/nm6077056\/","fullName":"Morfydd Clark","job":"actress","characters":["Galadriel"]},{"id":"nm8190914","url":"https:\/\/www.imdb.com\/name\/nm8190914\/","fullName":"Charlie Vickers","job":"actor","characters":["Sauron","Halbrand"]},{"id":"nm0249876","url":"https:\/\/www.imdb.com\/name\/nm0249876\/","fullName":"Charles Edwards","job":"actor","characters":["Lord Celebrimbor"]},{"id":"nm3033454","url":"https:\/\/www.imdb.com\/name\/nm3033454\/","fullName":"Ismael Cruz Cordova","job":"actor","characters":["Arondir"]},{"id":"nm7075019","url":"https:\/\/www.imdb.com\/name\/nm7075019\/","fullName":"Robert Aramayo","job":"actor","characters":["Elrond"]},{"id":"nm6003807","url":"https:\/\/www.imdb.com\/name\/nm6003807\/","fullName":"Robert Strange","job":"actor","characters":["Gl\u00fbg","Barrow-Wight","Dying Orc"]},{"id":"nm9220161","url":"https:\/\/www.imdb.com\/name\/nm9220161\/","fullName":"Markella Kavenagh","job":"actress","characters":["Nori Brandyfoot"]},{"id":"nm1621849","url":"https:\/\/www.imdb.com\/name\/nm1621849\/","fullName":"Daniel Weyman","job":"actor","characters":["The Stranger"]},{"id":"nm10090380","url":"https:\/\/www.imdb.com\/name\/nm10090380\/","fullName":"Megan Richards","job":"actress","characters":["Poppy Proudfellow"]},{"id":"nm1870963","url":"https:\/\/www.imdb.com\/name\/nm1870963\/","fullName":"Cynthia Addai-Robinson","job":"actress","characters":["Queen Regent M\u00edriel","M\u00edriel"]},{"id":"nm4259881","url":"https:\/\/www.imdb.com\/name\/nm4259881\/","fullName":"Patrick McKay","job":"writer","characters":[]},{"id":"nm4260438","url":"https:\/\/www.imdb.com\/name\/nm4260438\/","fullName":"John D. Payne","job":"writer","characters":[]},{"id":"nm0654197","url":"https:\/\/www.imdb.com\/name\/nm0654197\/","fullName":"Lloyd Owen","job":"actor","characters":["Captain Elendil","Elendil"]}],"totalSeasons":3,"totalEpisodes":17,"episodes":[{"id":"tt9788618","primaryTitle":"A Shadow of the Past","originalTitle":"A Shadow of the Past","seasonNumber":1,"episodeNumber":1,"runtimeMinutes":65,"averageRating":7.3,"numVotes":60342},{"id":"tt10582302","primaryTitle":"Adrift","originalTitle":"Adrift","seasonNumber":1,"episodeNumber":2,"runtimeMinutes":67,"averageRating":7.3,"numVotes":55577},{"id":"tt11609034","primaryTitle":"Adar","originalTitle":"Adar","seasonNumber":1,"episodeNumber":3,"runtimeMinutes":69,"averageRating":7.2,"numVotes":42739},{"id":"tt11609038","primaryTitle":"The Great Wave","originalTitle":"The Great Wave","seasonNumber":1,"episodeNumber":4,"runtimeMinutes":71,"averageRating":7,"numVotes":36727},{"id":"tt11609040","primaryTitle":"Partings","originalTitle":"Partings","seasonNumber":1,"episodeNumber":5,"runtimeMinutes":72,"averageRating":6.7,"numVotes":33489},{"id":"tt11609042","primaryTitle":"Ud\u00fbn","originalTitle":"Ud\u00fbn","seasonNumber":1,"episodeNumber":6,"runtimeMinutes":69,"averageRating":8.1,"numVotes":42607},{"id":"tt11609046","primaryTitle":"The Eye","originalTitle":"The Eye","seasonNumber":1,"episodeNumber":7,"runtimeMinutes":72,"averageRating":6.6,"numVotes":31866},{"id":"tt11609048","primaryTitle":"Alloyed","originalTitle":"Alloyed","seasonNumber":1,"episodeNumber":8,"runtimeMinutes":72,"averageRating":7.7,"numVotes":35302},{"id":"tt13580784","primaryTitle":"Elven Kings Under the Sky","originalTitle":"Elven Kings Under the Sky","seasonNumber":2,"episodeNumber":1,"runtimeMinutes":76,"averageRating":7.2,"numVotes":21235},{"id":"tt27580486","primaryTitle":"Where the Stars are Strange","originalTitle":"Where the Stars are Strange","seasonNumber":2,"episodeNumber":2,"runtimeMinutes":62,"averageRating":7,"numVotes":18974},{"id":"tt27580490","primaryTitle":"The Eagle and the Sceptre","originalTitle":"The Eagle and the Sceptre","seasonNumber":2,"episodeNumber":3,"runtimeMinutes":66,"averageRating":6.3,"numVotes":18819},{"id":"tt27580491","primaryTitle":"Eldest","originalTitle":"Eldest","seasonNumber":2,"episodeNumber":4,"runtimeMinutes":65,"averageRating":6.8,"numVotes":17476},{"id":"tt27580494","primaryTitle":"Halls of Stone","originalTitle":"Halls of Stone","seasonNumber":2,"episodeNumber":5,"runtimeMinutes":61,"averageRating":7.2,"numVotes":16256},{"id":"tt27580495","primaryTitle":"Where Is He?","originalTitle":"Where Is He?","seasonNumber":2,"episodeNumber":6,"runtimeMinutes":63,"averageRating":7.1,"numVotes":14874},{"id":"tt27580496","primaryTitle":"Doomed to Die","originalTitle":"Doomed to Die","seasonNumber":2,"episodeNumber":7,"runtimeMinutes":72,"averageRating":7.8,"numVotes":20562},{"id":"tt27580497","primaryTitle":"Shadow and Flame","originalTitle":"Shadow and Flame","seasonNumber":2,"episodeNumber":8,"runtimeMinutes":73,"averageRating":7.7,"numVotes":16226},{"id":"tt32446124","primaryTitle":"Episode #3.1","originalTitle":"Episode #3.1","seasonNumber":3,"episodeNumber":1,"runtimeMinutes":null,"averageRating":null,"numVotes":null}]}

Mind you that the developers of this API could have decided to use a query parameter in this case but depending on the structure of their API and RESTful measures they resorted to this which is the right way to go.

What is a Query Parameter?

A Query Parameter is a key-value pair that is added to the end of a URL to provide additional information to a web server or API. The key is a criterion whose value will be used in performing query operations, hence best used for searching, filtering, and sorting purposes. Let’s try making a request to the search endpoint GET Search**. Select the params tab and notice the list of optional query parameter fields. Get a movie title from the response you got when a request was made to GET Top 250 Movies** endpoint and fill in the original title field. The request will look like this if the title used is The Shawshank Redemption.

curl --request GET \
 --url 'https://imdb236.p.rapidapi.com/imdb/search?originalTitle=The%20Shawshank%20Redemption&type=movie&genre=Drama&rows=25&sortOrder=ASC&sortField=id' \
 --header 'x-rapidapi-host: imdb236.p.rapidapi.com' \
 --header 'x-rapidapi-key: {rapidapi-key}'

And here is the response,

{"rows":25,"numFound":1,"results":[{"id":"tt0111161","primaryTitle":"The Shawshank Redemption","originalTitle":"The Shawshank Redemption","type":"movie","description":"A banker convicted of uxoricide forms a friendship over a quarter century with a hardened convict, while maintaining his innocence and trying to remain hopeful through simple compassion.","primaryImage":"https:\/\/m.media-amazon.com\/images\/M\/MV5BMDAyY2FhYjctNDc5OS00MDNlLThiMGUtY2UxYWVkNGY2ZjljXkEyXkFqcGc@._V1_.jpg","contentRating":"R","isAdult":false,"releaseDate":"1994-10-14","startYear":1994,"endYear":null,"runtimeMinutes":142,"genres":["Drama"],"interests":["Epic","Period Drama","Prison Drama","Drama"],"countriesOfOrigin":["US"],"externalLinks":["https:\/\/www.facebook.com\/shawshankredemptionfilm\/","https:\/\/www.warnerbros.com\/movies\/shawshank-redemption"],"spokenLanguages":["en"],"filmingLocations":["Mansfield Reformatory - 100 Reformatory Road, Mansfield, Ohio, USA"],"productionCompanies":[{"id":"co0040620","name":"Castle Rock Entertainment"}],"budget":25000000,"grossWorldwide":29332133,"averageRating":9.3,"numVotes":2994403}],"nextCursorMark":"AoE\/ATFmYzFkYmIzN2Y0N2E1NmZhYWQ4M2IxMGM0YjQ3NDU1"}

A search can be made based on a lot of criteria, that’s how other query parameters can be included because it’s optional.

This request searches for a resource with the original title The Shawshank Redemption. All the query parameters used in this request have a key and a value which are used for fetching the right resource(s) based on the criteria provided. In this case, no specific resource is targeted, either one movie is returned or multiple movies that match the criteria are returned, so it varies. In scenarios where you want to perform filtering and sorting operations, query parameters are used.

Initially, I limited the scope to web developers, but in this age of AI where developers across domains interact with LLMs and APIs, understanding these standards is crucial for AI/ML engineers, data scientists, and various IT professionals. Because APIs are so common now, everyone needs to understand how they work.