# Pagination

Pagination makes sure that only a part (called **page**) of the resources is being returned during **GET** retrieval (listing). This is especially useful when a large amount of resources has been created. \
For example you may have created tens of thousands of rooms and it would be impractical to retrieve all of them in one GET request/response. That would put a huge strain on the bandwidth.

To paginate you need to use a combination of the following three parameters:

* **limit ->** limits the number of returned records in the page. Maximum and default value is **100**.
* **order ->** determines the sorting order of the result. Ascending (**asc**) or descending (**desc**). Default value is "**desc**" = descending and the order is by the `creation time` of the records.
* **after ->** used as a cursor to browse through all pages. That is the **id** of the last record from the previous page. For examples read immediately below.
* **offset** -> useful for table pagination where you want to retrieve records of a concrete page. The **after** param is on the contrary useful for infinite scroll type of pagination.

```
-- This returns maximum of 30 rooms sorted by descending order of creation time.
https://api.digitalsamba.com/api/v1/rooms?limit=30

-- This returns maximum of 30 rooms, sorted by ascending order of creation time
https://api.digitalsamba.com/api/v1/rooms?limit=30&order=asc

-- This returns maximum of 20 rooms, sorted by descending order of creation time.
-- Also includes the "after" cursor with a room id. 
-- Note that the provided value for "after" is just a random example.
https://api.digitalsamba.com/api/v1/rooms?limit=20&order=desc&after=48559760-8553-33d5-b016-a9efb48d37c7

-- This returns maximum of 20 rooms, sorted by descending order of creation time.
-- Also includes the "offset" param which skips 40 records, 
-- which means the 3rd page will be returned (20 * 2).
https://api.digitalsamba.com/api/v1/rooms?limit=20&offset=40&order=desc
```

#### Pseudocode example how to paginate through all of your rooms 

It loops using the **after** param as cursor until no more rooms are available.

```java
String BASE_ROOMS_URL = "https://api.digitalsamba.com/api/v1/rooms";

//This retrieves the 1st page (default limit is 100 items)
List<Room> room = getRooms(BASE_ROOMS_URL);

while (!rooms.isEmpty()) {
   //Process the current page according to your needs
   process(rooms);
   
   //Now retrieve the next page (default limit is again 100 items)
   Room lastRoomInPage = rooms.get(rooms.size() - 1);
   rooms = getRooms(BASE_ROOMS_URL + "?after=" + lastRoomInPage.getId());
}
```