Paginating our Course List

In This Lesson

We'll transform our courses list endpoint into a pagination endpoint. We'll check and validate our query string for a page and per page parameter that we'll then use to fetch pages of our courses.

Created by: @tomgobich
Published: 1 year ago

Join the Discussion 0 comments

Be the first to comment!

Transcript

So at present, our index method within our courses controller returns back an array of courses. As we have discussed though,
we want this to instead be a paginated list of our courses so that the users interfacing with our API can get one page at a time, X amount of courses per page.
So in order for us to turn this query into a paginated result, all that we need to do is suffix it with a call to the paginate method from Lucid. This paginate method accepts in two arguments,
the page number, which starts at one, not zero, and then the number that we want per page. I think there's a relatively new update to Lucid as well that adds an optional third argument to this
that accepts in a base URL for the paginate. And we'll discuss what that base URL is here momentarily. First though, let's go and just hard code in one as our page and then since we have, I think,
13 total courses that we've stubbed, let's go ahead and do five per page so that we should have three pages, two of which with five and then one with three courses.
So our pages will be five, five, and three there. If we were to instead do 10 per page, then that would be a single page of 10 and then another page of three. That's how that works.
And you can do however many per page you need. You could do a thousand if you wish. So let's go and give that a save and hop on over to Hopscotch real quick and send our getCoursesPaginateList out one more time.
The first thing that you're going to notice is we no longer get an array of our courses back, but rather an object with two properties. We have a meta property and a data property.
The data property contains a list of our courses. So this is an array of our course results, just a single page worth. So this is going to be five courses that we've queried here.
The meta property contains information about our paginator, the total number of courses that matched our query with the paginator. So we have 13 total there. The number that we're getting per page,
so that's five right there. The current page that we're on, the last page that we could potentially get. So since we have five per page, that's going to be three for our total of 13.
The first page that we could potentially get, so the inverse of last page there. And then we also have URL based properties for these as well.
We have first page URL, last page URL, next and previous. Since we're on page one, there is no previous page. That's why that is null. Now you'll notice that the URLs for these are just slash
and then it has the query string persisting of the page number applicable for that property. So first page is pointing to one, last page is pointing to three, next is pointing to two.
The base URL that we discussed a moment ago would allow us to prefix these URLs with a base URL. So let's dive back into our index method
and from our courses, let's do courses dot. And you'll see first that we have all of the standard array based methods at our disposal.
So we can filter, find all of that fun stuff, but we also have our pagination properties as well. So there's our current page. We also have last page, first page, everything that we saw within our pagination results
inside of the meta, but there's also this base URL method that allows us to specify what that base URL is that we want prefixed in front of all of our URL properties.
So let's go and import the router from AdonisJS core and make a URL with our identifier of API courses index.
And I'm also realizing that we want to add version one to that API name as well, to match with the actual URL prefix that we have going on too. So that with our versioning,
if we were to create a second group with version two, we'd be able to uniquely identify those via the name as well. So we'll do API.v1 there on our as prefix
with our route group for our version one. And that's going to change here as well. So it'll be API.v1 courses index. Okay, now that we have that prefixed,
let's jump back into Hopscotch, send this off one more time. And now you'll see all of these URL properties
now start with /API/version1/courses, which is exactly the URL that we're actually using to get this list of courses.
We have HTTP localhost 3333/API/version1 as our prefix here, and then /courses within the actual endpoint.
So if we were to do query string, page equals two, that would be the next page of results. Let's send that off. And you'll see that we're still on page number one.
That's because we're actually hard coding the current page that we're on within our query inside of our index method. So if we jump back into here, right here we have our hard coded page number one.
So what we wanna do next is make that dynamic. The best way to do that is via a validator. Now, in the previous series,
we set up a course validator with pagination in it as well. This is a simple vine object with a page and per page property, both of which are a type of number.
The page needs to be positive, so it cannot be negative, ensuring that our page number won't be invalid in that sense. And then since the max and min pages that we have
are dynamic based off of the query results, we can't quite do that unless we pass it specifically into this validator post query. So that doesn't make a whole lot of sense
to validate against at that much of a granular level. So this will suffice for that. And then our per page, we're just making sure that it's within a reasonable range there with a min and a max. You could also use the range rule,
which allows you to specify the numbers that it could be within the same as min and max there. And then this is optional. So let's go ahead and make use of this course paginate validator within our index method.
Since both of those are optional, it will allow us to set a default of one and then whatever page number we wish for when those are omitted.
So after we've authorized our organization's access token, we can go ahead and get our validated data. So await request validate using,
and we call that our course paginate validator. And then we can go ahead and just extract out the page and per page from there.
We can also default per page to five if it's omitted, and then we can default page to one if that is omitted as well. You could also do that directly down in a paginate method too.
Then we want to rig those up to our paginate method. So page there and per page, just like so. And let's give that a save, jump back in the hopscotch
and let's try for page number two once more. So when we send this off now, we see that our current page has switched from one to two and our next page URL is now pointing to three.
Furthermore, we can see that the IDs that we're getting back from our paginated data list start at six rather than I actually didn't pay any attention to what it was previously, what is it? So if we switch back to one here, send that off,
you can see, okay, it starts at one. That's, that makes sense. Okay, then if we get page number three, send that off, we should only get back three results
in this particular page because we're now on page three and we have 10 total. So that would leave three as a remainder.
So there's one, there's two, and there is the third and that is the last in our list. Perfect. Okay, now we don't have a page number four.
We don't have four pages worth of results, but let's see what happens if we send that off. Okay, great. So it still works okay. It just tells us that there's no data applicable for our results that we're after.
You see that our current page is at four and our data is empty there. So perfect, that works a-okay. And then if we were to also specify a per page,
so if we were to do two per page, send this off, we'll get back a validation statement saying that our per page must be at least five because we had that range of between five and 50.
If we switch this to 10, send this off, everything works a-okay. We still don't have a page number four, so let's switch to page number one again, send that off.
Okay, there we go. Now we should get back 10 data items. I'm not going to go through and count that, but we can verify via our meta that we now only have two total pages worth of results
and that we are getting 10 per page. So that's working a-okay there.

Adding an API to an AdonisJS Web App

43 Lessons

5h 31m

Introduction

API Authentication

Getting Started with APIs

Organization Resources

Courses

Searching

Rate Limiting

Rate Limiting an Organization's HTTP Requests

13m 59s

Stop losing your best ideas!

Use our integrated note feature to capture and organize your key insights. Take a note at any timestamp and jump instantly back to that moment in the video with a single click.