Instructor: The next and last part of the URL
is the Query Parameters.
So what are query parameters and when should we use them?
So the query parameters are used to query
the entities in GET method.
Now you might be wondering why do we need
query parameters when we have the ID parameter
which is also used to query the entities
and return a single entity.
So keep this question in mind.
We will come back to it later.
The query parameters come at the end of the URL
after a question mark and they are concatenated with &.
For example, it might look like this.
Note that after the orders entity we have a question mark
and then two parameters.
One is fromDate, with some date
and the other is toDate, with some other date.
So you can understand that what we are trying to do here
is fetch all the orders that were made
between the fromDate parameter and the toDate parameter.
So let's discuss the main differences
between query parameters and ID parameter
and when should we use each one?
So first, the location of them is different.
As we said, query parameters
come at the end of the URL
and the ID parameter comes at the end
or in the middle of the url,
depends if you have a sub entity.
Now how many parameters can I use
with each one of the parameter types?
So with query parameters,
I can use each number between zero and whatever,
and with the ID parameter, I can use only one parameter.
Now if you remember the examples that we discussed
then remember that with query parameters
we really used two parameters.
The fromDate and the toDate.
And the ID parameter is naturally only one parameter
because it specify a single entity.
It'll always be the ID
of the specific entity we want to retrieve.
Now here are examples of using
the query parameters and the ID parameter.
And we already discussed the way these parameters are used,
and here is the most important difference
between query parameters and the ID parameter,
and this is the return value.
With query parameters,
we may get back some unknown numbers of entity.
It could be nothing, it could be one
it could be two, it could be infinity, in theory, of course.
With the ID parameter,
we must return exactly one entity
and note the must in this sentence.
The whole idea of the ID parameter
is that the entity exists and therefore I must return it.
There is no way that using the ID parameter,
no entity is returned.
So what happens when no entities are found using
query parameters or using the ID parameter?
So with the query parameters, that's fine.
We already said that query parameters
may return entities and may not.
Remembering our example with the fromDate and toDate,
there may be no orders at all that were made
between those dates.
And it's perfectly fine if no entity will be returned.
But if I specify an ID parameter
and there is no entity with this ID
then the server should return an error.
Whatever we will see later in the section
about the response codes.
But it is an error.
Okay, so now let's see how to use query parameters.
So back to Beeceptor.
We would like to add a parameter that says
what is the first letter of the item
that we want to retrieve.
So we will do something like this.
Question mark
starts with
equal a.
So what you basically do here is asking the API
to bring us all the items of order number 17
that start with the letter a.
Okay, so now we have a complete URL
and let's test it using Postman.
So I'll just copy it
and let's modify the response
that we're expecting from this API.
And let's build a JSON construct
that contains some data about the items.
So we'll do it like this items
and this would be an array of items.
So item
name.
Now remember we ask for items that begin with letter a.
So we will do just that.
The name of this item will be Artwork.
I always loved this word.
And let's give it also an ID,
which would be 56,
and another one
called
Aircraft,
which has an ID of
123.
And let's close the array
and close the construct and save the rule.
Great, so now let's go to Postman and check this URL.
Okay, so here we are in Postman
and let's paste the URL we built here
and modify the verb to GET
and let's hit Send and see what happens.
And this is exactly what we expected to see.
We see the JSON that we defined in Beeceptor.
We got it back just as expected
as a response for the URL that we used.
Now notice something interesting?
Do you see the green dot here, near Params?
Click it and you see that Postman pass the URL
And so there is a parameter here,
this startsWith,
so it shows us there is a parameter with the key startsWith,
and the value a.
Okay, great.
So we have learned how to construct a simple,
readable, and very easy to use REST API url.
And I hope you understand the importance
of building such a URL and the various components of it.
But before we conclude this section
there is another topic that we need to discuss.