We will see what the Query String is and how to compose application routes that are capable of receiving data in the URL (any key/value set). We will explain how to receive the data in the controller with the @Query decorator.
They are capable of receiving different information on the requests made by customers. In the Nest Handbook we have learned to and through , but there are still other possibilities to explore.
One of the most basic and widely used ways to receive data in a route is the so-called “query string”, which basically consists of sending any set of data in the URL, so that it can be processed by applications.
What is Query String
Query String is the typical way in which data is sent in Get requests, using the same string as the url. Through this mechanism we can send any key/value data setexpressed in the address of the resource being accessed.
The URLs that send data by Query String have this form:
http://example.com?data1=value1&data2=value2
In the previous URL we would be sending two data:
- data1 with the value “value1”
- data2 with the value “value2”
Sending data in the URL is not considered very elegant, because the data appears in the same address and is very visible to the user. It could even happen that the user manually manipulates this data, which could affect the operation of the applications. However, it has some important advantages, such as the fact that deep links can be created capable of sending data from the client to the server. Those deep links could be distributed in various ways, for example in an email. In addition, complex URLs can be saved in bookmarks that send data to the server.
In fact, the advantages of using Query String are what make services like Google use this mechanism when we do a search with the search engine. For example, we can do a search, copy the URL and pass it to an email or WhatsApp message, for example.
How query string data is received in Nest controllers
Receiving the data from the query string is very simple and, as you might imagine, is done via a decorator, in this case @Query().
Basically we declare a parameter in the controller method that we decorate with @Queryas you can see below.
@Get(‘query’) queryPath(@Query() query) { return query; }
Of course, we must not forget to import the decorators we use:
import { Controller, Get, Query } from ‘@nestjs/common’;
This will allow receiving an object in the “query” parameter that will have all the data that is being sent in the URL.
Therefore, if we compose a URL like this:
http://localhost:3000/query?x=24&y=xxx
The value that will be injected into the query parameter will be this object:
{ “x”: “24”, “y”: “xxx” }
Since the query parameter is an object, we can perfectly access its properties precisely:
return `The data query.x has received the value ${query.x}`;
Of course, query is the name of a parameter, we could name it whatever we want. Obviously, the @Query() decorator decorates any parameter where you want to receive the data from the query string.
How to receive a specific variable by Query String
Sometimes we do not need to receive all possible variables from the Query String and we only need one piece of information. In the @Query() decorator we can simply indicate which variable of the Query String you want to receive and Nest will deliver it to us, instead of delivering the entire object complete with all possible data sent.
Let’s assume that we need to receive a variable called “count”, with a URL that would look like this:
http://localhost:3000/cars?count=3
By declaring the controller method we can receive that data in a unique way, indicating it in the @Query() decorator as a parameter. It would be more or less like this:
@Get(‘cars’) carsQuery(@Query(‘count’) carCount: number) { return carCount; }
Now, the value that will arrive to the “carCount” parameter would be the one sent in the URL. Just the data, if it exists.
You must be careful because, if the data “count” is not sent in the URL, since we have typed the data as “number”, it will deliver NaN (Not a Number). If we hadn’t typed carCount it would return an empty string.
How to validate a data that arrives in a Query String in a controller method
The data we are receiving may be essential for the operation of the application. Validating this data is very easy in Nest thanks to the use of pipes.
Let’s imagine that in the previous route (cars?count=3) it is essential to receive the variable count and make sure it’s an integer. If it isn’t, then we don’t want to execute anything in that path, but send an error message to the client.
In this case we can make use of the “ParseIntPipe” pipe provided by the framework, which does exactly the function of validating the data and converting it to the number type within the method.
We have not seen pipes yet and it is something important that we are going to address in , so if you have any questions you can consult the following chapters where we will see them in detail. At the moment we have here a simple sample of using some pipes.
@Get(‘cars’) carsQuery(@Query(‘count’, ParseIntPipe) carCount: number) { return carCount; }
You will have to import the pipe from @nestjs/common:
import { ParseIntPipe } from ‘@nestjs/common’;
Now, if you don’t pass us the “count” data through the query string, or if you pass us a value that is not specifically an integer, the application will automatically throw an error message and the controller method will not be executed.
The message will look like this:
{ “statusCode”: 400, “message”: “Validation failed (numeric string is expected)”, “error”: “Bad Request” }
conclusion
For now, this is all you need to know about how to receive data sent by the URL, using a query string. As you can see, it’s not very complicated to do in controllers and to some extent it’s very similar to how we received parameter data with @Param().
Throughout the we have given a good review of many of the things that we can do with controllers in Nest. They are one of the most important pieces of any application with this framework, so we will return to them several times, but in the following articles we are going to change the third, to start with .
Facebook Comments
Disqus